4 |
4 |
5 [![Build Status](https://travis-ci.org/spf13/afero.svg)](https://travis-ci.org/spf13/afero) [![Build status](https://ci.appveyor.com/api/projects/status/github/spf13/afero?branch=master&svg=true)](https://ci.appveyor.com/project/spf13/afero) [![GoDoc](https://godoc.org/github.com/spf13/afero?status.svg)](https://godoc.org/github.com/spf13/afero) [![Join the chat at https://gitter.im/spf13/afero](https://badges.gitter.im/Dev%20Chat.svg)](https://gitter.im/spf13/afero?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
5 [![Build Status](https://travis-ci.org/spf13/afero.svg)](https://travis-ci.org/spf13/afero) [![Build status](https://ci.appveyor.com/api/projects/status/github/spf13/afero?branch=master&svg=true)](https://ci.appveyor.com/project/spf13/afero) [![GoDoc](https://godoc.org/github.com/spf13/afero?status.svg)](https://godoc.org/github.com/spf13/afero) [![Join the chat at https://gitter.im/spf13/afero](https://badges.gitter.im/Dev%20Chat.svg)](https://gitter.im/spf13/afero?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
6 |
6 |
7 # Overview |
7 # Overview |
8 |
8 |
9 Afero is an filesystem framework providing a simple, uniform and universal API |
9 Afero is a filesystem framework providing a simple, uniform and universal API |
10 interacting with any filesystem, as an abstraction layer providing interfaces, |
10 interacting with any filesystem, as an abstraction layer providing interfaces, |
11 types and methods. Afero has an exceptionally clean interface and simple design |
11 types and methods. Afero has an exceptionally clean interface and simple design |
12 without needless constructors or initialization methods. |
12 without needless constructors or initialization methods. |
13 |
13 |
14 Afero is also a library providing a base set of interoperable backend |
14 Afero is also a library providing a base set of interoperable backend |
16 and benefit of the os and ioutil packages. |
16 and benefit of the os and ioutil packages. |
17 |
17 |
18 Afero provides significant improvements over using the os package alone, most |
18 Afero provides significant improvements over using the os package alone, most |
19 notably the ability to create mock and testing filesystems without relying on the disk. |
19 notably the ability to create mock and testing filesystems without relying on the disk. |
20 |
20 |
21 It is suitable for use in a any situation where you would consider using the OS |
21 It is suitable for use in any situation where you would consider using the OS |
22 package as it provides an additional abstraction that makes it easy to use a |
22 package as it provides an additional abstraction that makes it easy to use a |
23 memory backed file system during testing. It also adds support for the http |
23 memory backed file system during testing. It also adds support for the http |
24 filesystem for full interoperability. |
24 filesystem for full interoperability. |
25 |
25 |
26 |
26 |
31 * A set of interfaces to encourage and enforce interoperability between backends |
31 * A set of interfaces to encourage and enforce interoperability between backends |
32 * An atomic cross platform memory backed file system |
32 * An atomic cross platform memory backed file system |
33 * Support for compositional (union) file systems by combining multiple file systems acting as one |
33 * Support for compositional (union) file systems by combining multiple file systems acting as one |
34 * Specialized backends which modify existing filesystems (Read Only, Regexp filtered) |
34 * Specialized backends which modify existing filesystems (Read Only, Regexp filtered) |
35 * A set of utility functions ported from io, ioutil & hugo to be afero aware |
35 * A set of utility functions ported from io, ioutil & hugo to be afero aware |
36 |
36 * Wrapper for go 1.16 filesystem abstraction `io/fs.FS` |
37 |
37 |
38 # Using Afero |
38 # Using Afero |
39 |
39 |
40 Afero is easy to use and easier to adopt. |
40 Afero is easy to use and easier to adopt. |
41 |
41 |
42 A few different ways you could use Afero: |
42 A few different ways you could use Afero: |
43 |
43 |
44 * Use the interfaces alone to define you own file system. |
44 * Use the interfaces alone to define your own file system. |
45 * Wrap for the OS packages. |
45 * Wrapper for the OS packages. |
46 * Define different filesystems for different parts of your application. |
46 * Define different filesystems for different parts of your application. |
47 * Use Afero for mock filesystems while testing |
47 * Use Afero for mock filesystems while testing |
48 |
48 |
49 ## Step 1: Install Afero |
49 ## Step 1: Install Afero |
50 |
50 |
92 ## List of all available functions |
92 ## List of all available functions |
93 |
93 |
94 File System Methods Available: |
94 File System Methods Available: |
95 ```go |
95 ```go |
96 Chmod(name string, mode os.FileMode) : error |
96 Chmod(name string, mode os.FileMode) : error |
|
97 Chown(name string, uid, gid int) : error |
97 Chtimes(name string, atime time.Time, mtime time.Time) : error |
98 Chtimes(name string, atime time.Time, mtime time.Time) : error |
98 Create(name string) : File, error |
99 Create(name string) : File, error |
99 Mkdir(name string, perm os.FileMode) : error |
100 Mkdir(name string, perm os.FileMode) : error |
100 MkdirAll(path string, perm os.FileMode) : error |
101 MkdirAll(path string, perm os.FileMode) : error |
101 Name() : string |
102 Name() : string |
225 calls. It also makes it trivial to have your code use the OS during |
226 calls. It also makes it trivial to have your code use the OS during |
226 operation and a mock filesystem during testing or as needed. |
227 operation and a mock filesystem during testing or as needed. |
227 |
228 |
228 ```go |
229 ```go |
229 appfs := afero.NewOsFs() |
230 appfs := afero.NewOsFs() |
230 appfs.MkdirAll("src/a", 0755)) |
231 appfs.MkdirAll("src/a", 0755) |
231 ``` |
232 ``` |
232 |
233 |
233 ## Memory Backed Storage |
234 ## Memory Backed Storage |
234 |
235 |
235 ### MemMapFs |
236 ### MemMapFs |
239 necessary. It is fully concurrent and will work within go routines |
240 necessary. It is fully concurrent and will work within go routines |
240 safely. |
241 safely. |
241 |
242 |
242 ```go |
243 ```go |
243 mm := afero.NewMemMapFs() |
244 mm := afero.NewMemMapFs() |
244 mm.MkdirAll("src/a", 0755)) |
245 mm.MkdirAll("src/a", 0755) |
245 ``` |
246 ``` |
246 |
247 |
247 #### InMemoryFile |
248 #### InMemoryFile |
248 |
249 |
249 As part of MemMapFs, Afero also provides an atomic, fully concurrent memory |
250 As part of MemMapFs, Afero also provides an atomic, fully concurrent memory |
304 Afero provides an httpFs file system which satisfies this requirement. |
305 Afero provides an httpFs file system which satisfies this requirement. |
305 Any Afero FileSystem can be used as an httpFs. |
306 Any Afero FileSystem can be used as an httpFs. |
306 |
307 |
307 ```go |
308 ```go |
308 httpFs := afero.NewHttpFs(<ExistingFS>) |
309 httpFs := afero.NewHttpFs(<ExistingFS>) |
309 fileserver := http.FileServer(httpFs.Dir(<PATH>))) |
310 fileserver := http.FileServer(httpFs.Dir(<PATH>)) |
310 http.Handle("/", fileserver) |
311 http.Handle("/", fileserver) |
311 ``` |
312 ``` |
312 |
313 |
313 ## Composite Backends |
314 ## Composite Backends |
314 |
315 |
404 It's also nice that unlike some of my other libraries (hugo, cobra, viper) it |
403 It's also nice that unlike some of my other libraries (hugo, cobra, viper) it |
405 Googles very well. |
404 Googles very well. |
406 |
405 |
407 ## Release Notes |
406 ## Release Notes |
408 |
407 |
409 * **0.10.0** 2015.12.10 |
408 See the [Releases Page](https://github.com/spf13/afero/releases). |
410 * Full compatibility with Windows |
|
411 * Introduction of afero utilities |
|
412 * Test suite rewritten to work cross platform |
|
413 * Normalize paths for MemMapFs |
|
414 * Adding Sync to the file interface |
|
415 * **Breaking Change** Walk and ReadDir have changed parameter order |
|
416 * Moving types used by MemMapFs to a subpackage |
|
417 * General bugfixes and improvements |
|
418 * **0.9.0** 2015.11.05 |
|
419 * New Walk function similar to filepath.Walk |
|
420 * MemMapFs.OpenFile handles O_CREATE, O_APPEND, O_TRUNC |
|
421 * MemMapFs.Remove now really deletes the file |
|
422 * InMemoryFile.Readdir and Readdirnames work correctly |
|
423 * InMemoryFile functions lock it for concurrent access |
|
424 * Test suite improvements |
|
425 * **0.8.0** 2014.10.28 |
|
426 * First public version |
|
427 * Interfaces feel ready for people to build using |
|
428 * Interfaces satisfy all known uses |
|
429 * MemMapFs passes the majority of the OS test suite |
|
430 * OsFs passes the majority of the OS test suite |
|
431 |
409 |
432 ## Contributing |
410 ## Contributing |
433 |
411 |
434 1. Fork it |
412 1. Fork it |
435 2. Create your feature branch (`git checkout -b my-new-feature`) |
413 2. Create your feature branch (`git checkout -b my-new-feature`) |