README

afero logo-sm

A FileSystem Abstraction System for Go

Build Status Build status GoDoc

Overview

Afero is a filesystem framework providing a simple, uniform and universal API interacting with any filesystem, as an abstraction layer providing interfaces, types and methods. Afero has an exceptionally clean interface and simple design without needless constructors or initialization methods.

Afero is also a library providing a base set of interoperable backend filesystems that make it easy to work with afero while retaining all the power and benefit of the os and ioutil packages.

Afero provides significant improvements over using the os package alone, most notably the ability to create mock and testing filesystems without relying on the disk.

It is suitable for use in any situation where you would consider using the OS package as it provides an additional abstraction that makes it easy to use a memory backed file system during testing. It also adds support for the http filesystem for full interoperability.

Afero Features

  • A single consistent API for accessing a variety of filesystems
  • Interoperation between a variety of file system types
  • A set of interfaces to encourage and enforce interoperability between backends
  • An atomic cross platform memory backed file system
  • Support for compositional (union) file systems by combining multiple file systems acting as one
  • Specialized backends which modify existing filesystems (Read Only, Regexp filtered)
  • A set of utility functions ported from io, ioutil & hugo to be afero aware
  • Wrapper for go 1.16 filesystem abstraction io/fs.FS

Using Afero

Afero is easy to use and easier to adopt.

A few different ways you could use Afero:

  • Use the interfaces alone to define your own file system.
  • Wrapper for the OS packages.
  • Define different filesystems for different parts of your application.
  • Use Afero for mock filesystems while testing

Step 1: Install Afero

First use go get to install the latest version of the library.

$ go get github.com/spf13/afero

Next include Afero in your application.

import "github.com/spf13/afero"

Step 2: Declare a backend

First define a package variable and set it to a pointer to a filesystem.

var AppFs = afero.NewMemMapFs()

or

var AppFs = afero.NewOsFs()

It is important to note that if you repeat the composite literal you will be using a completely new and isolated filesystem. In the case of OsFs it will still use the same underlying filesystem but will reduce the ability to drop in other filesystems as desired.

Step 3: Use it like you would the OS package

Throughout your application use any function and method like you normally would.

So if my application before had:

os.Open('/tmp/foo')

We would replace it with:

AppFs.Open('/tmp/foo')

AppFs being the variable we defined above.

List of all available functions

File System Methods Available:

Chmod(name string, mode os.FileMode) : error
Chown(name string, uid, gid int) : error
Chtimes(name string, atime time.Time, mtime time.Time) : error
Create(name string) : File, error
Mkdir(name string, perm os.FileMode) : error
MkdirAll(path string, perm os.FileMode) : error
Name() : string
Open(name string) : File, error
OpenFile(name string, flag int, perm os.FileMode) : File, error
Remove(name string) : error
RemoveAll(path string) : error
Rename(oldname, newname string) : error
Stat(name string) : os.FileInfo, error

File Interfaces and Methods Available:

io.Closer
io.Reader
io.ReaderAt
io.Seeker
io.Writer
io.WriterAt

Name() : string
Readdir(count int) : []os.FileInfo, error
Readdirnames(n int) : []string, error
Stat() : os.FileInfo, error
Sync() : error
Truncate(size int64) : error
WriteString(s string) : ret int, err error

In some applications it may make sense to define a new package that simply exports the file system variable for easy access from anywhere.

Using Afero's utility functions

Afero provides a set of functions to make it easier to use the underlying file systems. These functions have been primarily ported from io & ioutil with some developed for Hugo.

The afero utilities support all afero compatible backends.

The list of utilities includes:

DirExists(path string) (bool, error)
Exists(path string) (bool, error)
FileContainsBytes(filename string, subslice []byte) (bool, error)
GetTempDir(subPath string) string
IsDir(path string) (bool, error)
IsEmpty(path string) (bool, error)
ReadDir(dirname string) ([]os.FileInfo, error)
ReadFile(filename string) ([]byte, error)
SafeWriteReader(path string, r io.Reader) (err error)
TempDir(dir, prefix string) (name string, err error)
TempFile(dir, prefix string) (f File, err error)
Walk(root string, walkFn filepath.WalkFunc) error
WriteFile(filename string, data []byte, perm os.FileMode) error
WriteReader(path string, r io.Reader) (err error)

For a complete list see Afero's GoDoc

They are available under two different approaches to use. You can either call them directly where the first parameter of each function will be the file system, or you can declare a new Afero, a custom type used to bind these functions as methods to a given filesystem.

Calling utilities directly
fs := new(afero.MemMapFs)
f, err := afero.TempFile(fs,"", "ioutil-test")

Calling via Afero
fs := afero.NewMemMapFs()
afs := &afero.Afero{Fs: fs}
f, err := afs.TempFile("", "ioutil-test")

Using Afero for Testing

There is a large benefit to using a mock filesystem for testing. It has a completely blank state every time it is initialized and can be easily reproducible regardless of OS. You could create files to your heart’s content and the file access would be fast while also saving you from all the annoying issues with deleting temporary files, Windows file locking, etc. The MemMapFs backend is perfect for testing.

  • Much faster than performing I/O operations on disk
  • Avoid security issues and permissions
  • Far more control. 'rm -rf /' with confidence
  • Test setup is far more easier to do
  • No test cleanup needed

One way to accomplish this is to define a variable as mentioned above. In your application this will be set to afero.NewOsFs() during testing you can set it to afero.NewMemMapFs().

It wouldn't be uncommon to have each test initialize a blank slate memory backend. To do this I would define my appFS = afero.NewOsFs() somewhere appropriate in my application code. This approach ensures that Tests are order independent, with no test relying on the state left by an earlier test.

Then in my tests I would initialize a new MemMapFs for each test:

func TestExist(t *testing.T) {
	appFS := afero.NewMemMapFs()
	// create test files and directories
	appFS.MkdirAll("src/a", 0755)
	afero.WriteFile(appFS, "src/a/b", []byte("file b"), 0644)
	afero.WriteFile(appFS, "src/c", []byte("file c"), 0644)
	name := "src/c"
	_, err := appFS.Stat(name)
	if os.IsNotExist(err) {
		t.Errorf("file \"%s\" does not exist.\n", name)
	}
}

Available Backends

Operating System Native

OsFs

The first is simply a wrapper around the native OS calls. This makes it very easy to use as all of the calls are the same as the existing OS calls. It also makes it trivial to have your code use the OS during operation and a mock filesystem during testing or as needed.

appfs := afero.NewOsFs()
appfs.MkdirAll("src/a", 0755)

Memory Backed Storage

MemMapFs

Afero also provides a fully atomic memory backed filesystem perfect for use in mocking and to speed up unnecessary disk io when persistence isn’t necessary. It is fully concurrent and will work within go routines safely.

mm := afero.NewMemMapFs()
mm.MkdirAll("src/a", 0755)
InMemoryFile

As part of MemMapFs, Afero also provides an atomic, fully concurrent memory backed file implementation. This can be used in other memory backed file systems with ease. Plans are to add a radix tree memory stored file system using InMemoryFile.

Network Interfaces

SftpFs

Afero has experimental support for secure file transfer protocol (sftp). Which can be used to perform file operations over a encrypted channel.

Filtering Backends

BasePathFs

The BasePathFs restricts all operations to a given path within an Fs. The given file name to the operations on this Fs will be prepended with the base path before calling the source Fs.

bp := afero.NewBasePathFs(afero.NewOsFs(), "/base/path")
ReadOnlyFs

A thin wrapper around the source Fs providing a read only view.

fs := afero.NewReadOnlyFs(afero.NewOsFs())
_, err := fs.Create("/file.txt")
// err = syscall.EPERM

RegexpFs

A filtered view on file names, any file NOT matching the passed regexp will be treated as non-existing. Files not matching the regexp provided will not be created. Directories are not filtered.

fs := afero.NewRegexpFs(afero.NewMemMapFs(), regexp.MustCompile(`\.txt$`))
_, err := fs.Create("/file.html")
// err = syscall.ENOENT
HttpFs

Afero provides an http compatible backend which can wrap any of the existing backends.

The Http package requires a slightly specific version of Open which returns an http.File type.

Afero provides an httpFs file system which satisfies this requirement. Any Afero FileSystem can be used as an httpFs.

httpFs := afero.NewHttpFs(<ExistingFS>)
fileserver := http.FileServer(httpFs.Dir(<PATH>))
http.Handle("/", fileserver)

Composite Backends

Afero provides the ability have two filesystems (or more) act as a single file system.

CacheOnReadFs

The CacheOnReadFs will lazily make copies of any accessed files from the base layer into the overlay. Subsequent reads will be pulled from the overlay directly permitting the request is within the cache duration of when it was created in the overlay.

If the base filesystem is writeable, any changes to files will be done first to the base, then to the overlay layer. Write calls to open file handles like Write() or Truncate() to the overlay first.

To writing files to the overlay only, you can use the overlay Fs directly (not via the union Fs).

Cache files in the layer for the given time.Duration, a cache duration of 0 means "forever" meaning the file will not be re-requested from the base ever.

A read-only base will make the overlay also read-only but still copy files from the base to the overlay when they're not present (or outdated) in the caching layer.

base := afero.NewOsFs()
layer := afero.NewMemMapFs()
ufs := afero.NewCacheOnReadFs(base, layer, 100 * time.Second)
CopyOnWriteFs()

The CopyOnWriteFs is a read only base file system with a potentially writeable layer on top.

Read operations will first look in the overlay and if not found there, will serve the file from the base.

Changes to the file system will only be made in the overlay.

Any attempt to modify a file found only in the base will copy the file to the overlay layer before modification (including opening a file with a writable handle).

Removing and Renaming files present only in the base layer is not currently permitted. If a file is present in the base layer and the overlay, only the overlay will be removed/renamed.

	base := afero.NewOsFs()
	roBase := afero.NewReadOnlyFs(base)
	ufs := afero.NewCopyOnWriteFs(roBase, afero.NewMemMapFs())

	fh, _ = ufs.Create("/home/test/file2.txt")
	fh.WriteString("This is a test")
	fh.Close()

In this example all write operations will only occur in memory (MemMapFs) leaving the base filesystem (OsFs) untouched.

Desired/possible backends

The following is a short list of possible backends we hope someone will implement:

  • SSH
  • S3

About the project

What's in the name

Afero comes from the latin roots Ad-Facere.

"Ad" is a prefix meaning "to".

"Facere" is a form of the root "faciō" making "make or do".

The literal meaning of afero is "to make" or "to do" which seems very fitting for a library that allows one to make files and directories and do things with them.

The English word that shares the same roots as Afero is "affair". Affair shares the same concept but as a noun it means "something that is made or done" or "an object of a particular type".

It's also nice that unlike some of my other libraries (hugo, cobra, viper) it Googles very well.

Release Notes

See the Releases Page.

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Contributors

Names in no particular order:

License

Afero is released under the Apache 2.0 license. See LICENSE.txt

Expand ▾ Collapse ▴

Documentation

Index

Constants

View Source
const BADFD = syscall.EBADFD
View Source
const FilePathSeparator = string(filepath.Separator)

    Filepath separator defined by os.Separator.

    Variables

    View Source
    var (
    	ErrFileClosed        = errors.New("File is closed")
    	ErrOutOfRange        = errors.New("Out of range")
    	ErrTooLarge          = errors.New("Too large")
    	ErrFileNotFound      = os.ErrNotExist
    	ErrFileExists        = os.ErrExist
    	ErrDestinationExists = os.ErrExist
    )
    View Source
    var ErrNoReadlink = errors.New("readlink not supported")

      ErrNoReadlink is the error that will be wrapped in an os.Path if a file system does not support the readlink operation either directly or through its delegated filesystem. As expressed by support for the LinkReader interface.

      View Source
      var ErrNoSymlink = errors.New("symlink not supported")

        ErrNoSymlink is the error that will be wrapped in an os.LinkError if a file system does not support Symlink's either directly or through its delegated filesystem. As expressed by support for the Linker interface.

        Functions

        func DirExists

        func DirExists(fs Fs, path string) (bool, error)

          DirExists checks if a path exists and is a directory.

          func Exists

          func Exists(fs Fs, path string) (bool, error)

            Check if a file or directory exists.

            func FileContainsAnyBytes

            func FileContainsAnyBytes(fs Fs, filename string, subslices [][]byte) (bool, error)

              Check if a file contains any of the specified byte slices.

              func FileContainsBytes

              func FileContainsBytes(fs Fs, filename string, subslice []byte) (bool, error)

                Check if a file contains a specified byte slice.

                func FullBaseFsPath

                func FullBaseFsPath(basePathFs *BasePathFs, relativePath string) string

                func GetTempDir

                func GetTempDir(fs Fs, subPath string) string

                  GetTempDir returns the default temp directory with trailing slash if subPath is not empty then it will be created recursively with mode 777 rwx rwx rwx

                  func Glob

                  func Glob(fs Fs, pattern string) (matches []string, err error)

                    Glob returns the names of all files matching pattern or nil if there is no matching file. The syntax of patterns is the same as in Match. The pattern may describe hierarchical names such as /usr/*/bin/ed (assuming the Separator is '/').

                    Glob ignores file system errors such as I/O errors reading directories. The only possible returned error is ErrBadPattern, when pattern is malformed.

                    This was adapted from (http://golang.org/pkg/path/filepath) and uses several built-ins from that package.

                    func IsDir

                    func IsDir(fs Fs, path string) (bool, error)

                      IsDir checks if a given path is a directory.

                      func IsEmpty

                      func IsEmpty(fs Fs, path string) (bool, error)

                        IsEmpty checks if a given file or directory is empty.

                        func NeuterAccents

                        func NeuterAccents(s string) string

                          Transform characters with accents into plain forms.

                          func ReadAll

                          func ReadAll(r io.Reader) ([]byte, error)

                            ReadAll reads from r until an error or EOF and returns the data it read. A successful call returns err == nil, not err == EOF. Because ReadAll is defined to read from src until EOF, it does not treat an EOF from Read as an error to be reported.

                            func ReadDir

                            func ReadDir(fs Fs, dirname string) ([]os.FileInfo, error)

                            func ReadFile

                            func ReadFile(fs Fs, filename string) ([]byte, error)

                            func SafeWriteReader

                            func SafeWriteReader(fs Fs, path string, r io.Reader) (err error)

                            func TempDir

                            func TempDir(fs Fs, dir, prefix string) (name string, err error)

                            func UnicodeSanitize

                            func UnicodeSanitize(s string) string

                              Rewrite string to remove non-standard path characters

                              func Walk

                              func Walk(fs Fs, root string, walkFn filepath.WalkFunc) error

                              func WriteFile

                              func WriteFile(fs Fs, filename string, data []byte, perm os.FileMode) error

                              func WriteReader

                              func WriteReader(fs Fs, path string, r io.Reader) (err error)

                              Types

                              type Afero

                              type Afero struct {
                              	Fs
                              }

                              func (Afero) DirExists

                              func (a Afero) DirExists(path string) (bool, error)

                              func (Afero) Exists

                              func (a Afero) Exists(path string) (bool, error)

                              func (Afero) FileContainsAnyBytes

                              func (a Afero) FileContainsAnyBytes(filename string, subslices [][]byte) (bool, error)

                              func (Afero) FileContainsBytes

                              func (a Afero) FileContainsBytes(filename string, subslice []byte) (bool, error)

                              func (Afero) GetTempDir

                              func (a Afero) GetTempDir(subPath string) string

                              func (Afero) IsDir

                              func (a Afero) IsDir(path string) (bool, error)

                              func (Afero) IsEmpty

                              func (a Afero) IsEmpty(path string) (bool, error)

                              func (Afero) ReadDir

                              func (a Afero) ReadDir(dirname string) ([]os.FileInfo, error)

                                ReadDir reads the directory named by dirname and returns a list of sorted directory entries.

                                func (Afero) ReadFile

                                func (a Afero) ReadFile(filename string) ([]byte, error)

                                  ReadFile reads the file named by filename and returns the contents. A successful call returns err == nil, not err == EOF. Because ReadFile reads the whole file, it does not treat an EOF from Read as an error to be reported.

                                  func (Afero) SafeWriteReader

                                  func (a Afero) SafeWriteReader(path string, r io.Reader) (err error)

                                    Same as WriteReader but checks to see if file/directory already exists.

                                    func (Afero) TempDir

                                    func (a Afero) TempDir(dir, prefix string) (name string, err error)

                                      TempDir creates a new temporary directory in the directory dir with a name beginning with prefix and returns the path of the new directory. If dir is the empty string, TempDir uses the default directory for temporary files (see os.TempDir). Multiple programs calling TempDir simultaneously will not choose the same directory. It is the caller's responsibility to remove the directory when no longer needed.

                                      func (Afero) TempFile

                                      func (a Afero) TempFile(dir, pattern string) (f File, err error)

                                        TempFile creates a new temporary file in the directory dir, opens the file for reading and writing, and returns the resulting *os.File. The filename is generated by taking pattern and adding a random string to the end. If pattern includes a "*", the random string replaces the last "*". If dir is the empty string, TempFile uses the default directory for temporary files (see os.TempDir). Multiple programs calling TempFile simultaneously will not choose the same file. The caller can use f.Name() to find the pathname of the file. It is the caller's responsibility to remove the file when no longer needed.

                                        func (Afero) Walk

                                        func (a Afero) Walk(root string, walkFn filepath.WalkFunc) error

                                        func (Afero) WriteFile

                                        func (a Afero) WriteFile(filename string, data []byte, perm os.FileMode) error

                                          WriteFile writes data to a file named by filename. If the file does not exist, WriteFile creates it with permissions perm; otherwise WriteFile truncates it before writing.

                                          func (Afero) WriteReader

                                          func (a Afero) WriteReader(path string, r io.Reader) (err error)

                                            Takes a reader and a path and writes the content

                                            type BasePathFile

                                            type BasePathFile struct {
                                            	File
                                            	// contains filtered or unexported fields
                                            }

                                            func (*BasePathFile) Name

                                            func (f *BasePathFile) Name() string

                                            type BasePathFs

                                            type BasePathFs struct {
                                            	// contains filtered or unexported fields
                                            }

                                              The BasePathFs restricts all operations to a given path within an Fs. The given file name to the operations on this Fs will be prepended with the base path before calling the base Fs. Any file name (after filepath.Clean()) outside this base path will be treated as non existing file.

                                              Note that it does not clean the error messages on return, so you may reveal the real path on errors.

                                              func (*BasePathFs) Chmod

                                              func (b *BasePathFs) Chmod(name string, mode os.FileMode) (err error)

                                              func (*BasePathFs) Chown

                                              func (b *BasePathFs) Chown(name string, uid, gid int) (err error)

                                              func (*BasePathFs) Chtimes

                                              func (b *BasePathFs) Chtimes(name string, atime, mtime time.Time) (err error)

                                              func (*BasePathFs) Create

                                              func (b *BasePathFs) Create(name string) (f File, err error)

                                              func (*BasePathFs) LstatIfPossible

                                              func (b *BasePathFs) LstatIfPossible(name string) (os.FileInfo, bool, error)

                                              func (*BasePathFs) Mkdir

                                              func (b *BasePathFs) Mkdir(name string, mode os.FileMode) (err error)

                                              func (*BasePathFs) MkdirAll

                                              func (b *BasePathFs) MkdirAll(name string, mode os.FileMode) (err error)

                                              func (*BasePathFs) Name

                                              func (b *BasePathFs) Name() string

                                              func (*BasePathFs) Open

                                              func (b *BasePathFs) Open(name string) (f File, err error)

                                              func (*BasePathFs) OpenFile

                                              func (b *BasePathFs) OpenFile(name string, flag int, mode os.FileMode) (f File, err error)

                                              func (*BasePathFs) ReadlinkIfPossible

                                              func (b *BasePathFs) ReadlinkIfPossible(name string) (string, error)

                                              func (*BasePathFs) RealPath

                                              func (b *BasePathFs) RealPath(name string) (path string, err error)

                                                on a file outside the base path it returns the given file name and an error, else the given file with the base path prepended

                                                func (*BasePathFs) Remove

                                                func (b *BasePathFs) Remove(name string) (err error)

                                                func (*BasePathFs) RemoveAll

                                                func (b *BasePathFs) RemoveAll(name string) (err error)

                                                func (*BasePathFs) Rename

                                                func (b *BasePathFs) Rename(oldname, newname string) (err error)

                                                func (*BasePathFs) Stat

                                                func (b *BasePathFs) Stat(name string) (fi os.FileInfo, err error)

                                                func (*BasePathFs) SymlinkIfPossible

                                                func (b *BasePathFs) SymlinkIfPossible(oldname, newname string) error

                                                type CacheOnReadFs

                                                type CacheOnReadFs struct {
                                                	// contains filtered or unexported fields
                                                }

                                                  If the cache duration is 0, cache time will be unlimited, i.e. once a file is in the layer, the base will never be read again for this file.

                                                  For cache times greater than 0, the modification time of a file is checked. Note that a lot of file system implementations only allow a resolution of a second for timestamps... or as the godoc for os.Chtimes() states: "The underlying filesystem may truncate or round the values to a less precise time unit."

                                                  This caching union will forward all write calls also to the base file system first. To prevent writing to the base Fs, wrap it in a read-only filter - Note: this will also make the overlay read-only, for writing files in the overlay, use the overlay Fs directly, not via the union Fs.

                                                  func (*CacheOnReadFs) Chmod

                                                  func (u *CacheOnReadFs) Chmod(name string, mode os.FileMode) error

                                                  func (*CacheOnReadFs) Chown

                                                  func (u *CacheOnReadFs) Chown(name string, uid, gid int) error

                                                  func (*CacheOnReadFs) Chtimes

                                                  func (u *CacheOnReadFs) Chtimes(name string, atime, mtime time.Time) error

                                                  func (*CacheOnReadFs) Create

                                                  func (u *CacheOnReadFs) Create(name string) (File, error)

                                                  func (*CacheOnReadFs) Mkdir

                                                  func (u *CacheOnReadFs) Mkdir(name string, perm os.FileMode) error

                                                  func (*CacheOnReadFs) MkdirAll

                                                  func (u *CacheOnReadFs) MkdirAll(name string, perm os.FileMode) error

                                                  func (*CacheOnReadFs) Name

                                                  func (u *CacheOnReadFs) Name() string

                                                  func (*CacheOnReadFs) Open

                                                  func (u *CacheOnReadFs) Open(name string) (File, error)

                                                  func (*CacheOnReadFs) OpenFile

                                                  func (u *CacheOnReadFs) OpenFile(name string, flag int, perm os.FileMode) (File, error)

                                                  func (*CacheOnReadFs) Remove

                                                  func (u *CacheOnReadFs) Remove(name string) error

                                                  func (*CacheOnReadFs) RemoveAll

                                                  func (u *CacheOnReadFs) RemoveAll(name string) error

                                                  func (*CacheOnReadFs) Rename

                                                  func (u *CacheOnReadFs) Rename(oldname, newname string) error

                                                  func (*CacheOnReadFs) Stat

                                                  func (u *CacheOnReadFs) Stat(name string) (os.FileInfo, error)

                                                  type CopyOnWriteFs

                                                  type CopyOnWriteFs struct {
                                                  	// contains filtered or unexported fields
                                                  }

                                                    The CopyOnWriteFs is a union filesystem: a read only base file system with a possibly writeable layer on top. Changes to the file system will only be made in the overlay: Changing an existing file in the base layer which is not present in the overlay will copy the file to the overlay ("changing" includes also calls to e.g. Chtimes(), Chmod() and Chown()).

                                                    Reading directories is currently only supported via Open(), not OpenFile().

                                                    func (*CopyOnWriteFs) Chmod

                                                    func (u *CopyOnWriteFs) Chmod(name string, mode os.FileMode) error

                                                    func (*CopyOnWriteFs) Chown

                                                    func (u *CopyOnWriteFs) Chown(name string, uid, gid int) error

                                                    func (*CopyOnWriteFs) Chtimes

                                                    func (u *CopyOnWriteFs) Chtimes(name string, atime, mtime time.Time) error

                                                    func (*CopyOnWriteFs) Create

                                                    func (u *CopyOnWriteFs) Create(name string) (File, error)

                                                    func (*CopyOnWriteFs) LstatIfPossible

                                                    func (u *CopyOnWriteFs) LstatIfPossible(name string) (os.FileInfo, bool, error)

                                                    func (*CopyOnWriteFs) Mkdir

                                                    func (u *CopyOnWriteFs) Mkdir(name string, perm os.FileMode) error

                                                    func (*CopyOnWriteFs) MkdirAll

                                                    func (u *CopyOnWriteFs) MkdirAll(name string, perm os.FileMode) error

                                                    func (*CopyOnWriteFs) Name

                                                    func (u *CopyOnWriteFs) Name() string

                                                    func (*CopyOnWriteFs) Open

                                                    func (u *CopyOnWriteFs) Open(name string) (File, error)

                                                      This function handles the 9 different possibilities caused by the union which are the intersection of the following...

                                                      layer: doesn't exist, exists as a file, and exists as a directory
                                                      base:  doesn't exist, exists as a file, and exists as a directory
                                                      

                                                      func (*CopyOnWriteFs) OpenFile

                                                      func (u *CopyOnWriteFs) OpenFile(name string, flag int, perm os.FileMode) (File, error)

                                                      func (*CopyOnWriteFs) ReadlinkIfPossible

                                                      func (u *CopyOnWriteFs) ReadlinkIfPossible(name string) (string, error)

                                                      func (*CopyOnWriteFs) Remove

                                                      func (u *CopyOnWriteFs) Remove(name string) error

                                                        Removing files present only in the base layer is not permitted. If a file is present in the base layer and the overlay, only the overlay will be removed.

                                                        func (*CopyOnWriteFs) RemoveAll

                                                        func (u *CopyOnWriteFs) RemoveAll(name string) error

                                                        func (*CopyOnWriteFs) Rename

                                                        func (u *CopyOnWriteFs) Rename(oldname, newname string) error

                                                          Renaming files present only in the base layer is not permitted

                                                          func (*CopyOnWriteFs) Stat

                                                          func (u *CopyOnWriteFs) Stat(name string) (os.FileInfo, error)

                                                          func (*CopyOnWriteFs) SymlinkIfPossible

                                                          func (u *CopyOnWriteFs) SymlinkIfPossible(oldname, newname string) error

                                                          type DirsMerger

                                                          type DirsMerger func(lofi, bofi []os.FileInfo) ([]os.FileInfo, error)

                                                            DirsMerger is how UnionFile weaves two directories together. It takes the FileInfo slices from the layer and the base and returns a single view.

                                                            type File

                                                            type File interface {
                                                            	io.Closer
                                                            	io.Reader
                                                            	io.ReaderAt
                                                            	io.Seeker
                                                            	io.Writer
                                                            	io.WriterAt
                                                            
                                                            	Name() string
                                                            	Readdir(count int) ([]os.FileInfo, error)
                                                            	Readdirnames(n int) ([]string, error)
                                                            	Stat() (os.FileInfo, error)
                                                            	Sync() error
                                                            	Truncate(size int64) error
                                                            	WriteString(s string) (ret int, err error)
                                                            }

                                                              File represents a file in the filesystem.

                                                              func TempFile

                                                              func TempFile(fs Fs, dir, pattern string) (f File, err error)

                                                              type Fs

                                                              type Fs interface {
                                                              	// Create creates a file in the filesystem, returning the file and an
                                                              	// error, if any happens.
                                                              	Create(name string) (File, error)
                                                              
                                                              	// Mkdir creates a directory in the filesystem, return an error if any
                                                              	// happens.
                                                              	Mkdir(name string, perm os.FileMode) error
                                                              
                                                              	// MkdirAll creates a directory path and all parents that does not exist
                                                              	// yet.
                                                              	MkdirAll(path string, perm os.FileMode) error
                                                              
                                                              	// Open opens a file, returning it or an error, if any happens.
                                                              	Open(name string) (File, error)
                                                              
                                                              	// OpenFile opens a file using the given flags and the given mode.
                                                              	OpenFile(name string, flag int, perm os.FileMode) (File, error)
                                                              
                                                              	// Remove removes a file identified by name, returning an error, if any
                                                              	// happens.
                                                              	Remove(name string) error
                                                              
                                                              	// RemoveAll removes a directory path and any children it contains. It
                                                              	// does not fail if the path does not exist (return nil).
                                                              	RemoveAll(path string) error
                                                              
                                                              	// Rename renames a file.
                                                              	Rename(oldname, newname string) error
                                                              
                                                              	// Stat returns a FileInfo describing the named file, or an error, if any
                                                              	// happens.
                                                              	Stat(name string) (os.FileInfo, error)
                                                              
                                                              	// The name of this FileSystem
                                                              	Name() string
                                                              
                                                              	// Chmod changes the mode of the named file to mode.
                                                              	Chmod(name string, mode os.FileMode) error
                                                              
                                                              	// Chown changes the uid and gid of the named file.
                                                              	Chown(name string, uid, gid int) error
                                                              
                                                              	//Chtimes changes the access and modification times of the named file
                                                              	Chtimes(name string, atime time.Time, mtime time.Time) error
                                                              }

                                                                Fs is the filesystem interface.

                                                                Any simulated or real filesystem should implement this interface.

                                                                func NewBasePathFs

                                                                func NewBasePathFs(source Fs, path string) Fs

                                                                func NewCacheOnReadFs

                                                                func NewCacheOnReadFs(base Fs, layer Fs, cacheTime time.Duration) Fs

                                                                func NewCopyOnWriteFs

                                                                func NewCopyOnWriteFs(base Fs, layer Fs) Fs

                                                                func NewMemMapFs

                                                                func NewMemMapFs() Fs

                                                                func NewOsFs

                                                                func NewOsFs() Fs

                                                                func NewReadOnlyFs

                                                                func NewReadOnlyFs(source Fs) Fs

                                                                func NewRegexpFs

                                                                func NewRegexpFs(source Fs, re *regexp.Regexp) Fs

                                                                type HttpFs

                                                                type HttpFs struct {
                                                                	// contains filtered or unexported fields
                                                                }

                                                                func NewHttpFs

                                                                func NewHttpFs(source Fs) *HttpFs

                                                                func (HttpFs) Chmod

                                                                func (h HttpFs) Chmod(name string, mode os.FileMode) error

                                                                func (HttpFs) Chown

                                                                func (h HttpFs) Chown(name string, uid, gid int) error

                                                                func (HttpFs) Chtimes

                                                                func (h HttpFs) Chtimes(name string, atime time.Time, mtime time.Time) error

                                                                func (HttpFs) Create

                                                                func (h HttpFs) Create(name string) (File, error)

                                                                func (HttpFs) Dir

                                                                func (h HttpFs) Dir(s string) *httpDir

                                                                func (HttpFs) Mkdir

                                                                func (h HttpFs) Mkdir(name string, perm os.FileMode) error

                                                                func (HttpFs) MkdirAll

                                                                func (h HttpFs) MkdirAll(path string, perm os.FileMode) error

                                                                func (HttpFs) Name

                                                                func (h HttpFs) Name() string

                                                                func (HttpFs) Open

                                                                func (h HttpFs) Open(name string) (http.File, error)

                                                                func (HttpFs) OpenFile

                                                                func (h HttpFs) OpenFile(name string, flag int, perm os.FileMode) (File, error)

                                                                func (HttpFs) Remove

                                                                func (h HttpFs) Remove(name string) error

                                                                func (HttpFs) RemoveAll

                                                                func (h HttpFs) RemoveAll(path string) error

                                                                func (HttpFs) Rename

                                                                func (h HttpFs) Rename(oldname, newname string) error

                                                                func (HttpFs) Stat

                                                                func (h HttpFs) Stat(name string) (os.FileInfo, error)

                                                                type LinkReader

                                                                type LinkReader interface {
                                                                	ReadlinkIfPossible(name string) (string, error)
                                                                }

                                                                  LinkReader is an optional interface in Afero. It is only implemented by the filesystems saying so.

                                                                  type Linker

                                                                  type Linker interface {
                                                                  	SymlinkIfPossible(oldname, newname string) error
                                                                  }

                                                                    Linker is an optional interface in Afero. It is only implemented by the filesystems saying so. It will call Symlink if the filesystem itself is, or it delegates to, the os filesystem, or the filesystem otherwise supports Symlink's.

                                                                    type Lstater

                                                                    type Lstater interface {
                                                                    	LstatIfPossible(name string) (os.FileInfo, bool, error)
                                                                    }

                                                                      Lstater is an optional interface in Afero. It is only implemented by the filesystems saying so. It will call Lstat if the filesystem iself is, or it delegates to, the os filesystem. Else it will call Stat. In addtion to the FileInfo, it will return a boolean telling whether Lstat was called or not.

                                                                      type MemMapFs

                                                                      type MemMapFs struct {
                                                                      	// contains filtered or unexported fields
                                                                      }

                                                                      func (*MemMapFs) Chmod

                                                                      func (m *MemMapFs) Chmod(name string, mode os.FileMode) error

                                                                      func (*MemMapFs) Chown

                                                                      func (m *MemMapFs) Chown(name string, uid, gid int) error

                                                                      func (*MemMapFs) Chtimes

                                                                      func (m *MemMapFs) Chtimes(name string, atime time.Time, mtime time.Time) error

                                                                      func (*MemMapFs) Create

                                                                      func (m *MemMapFs) Create(name string) (File, error)

                                                                      func (*MemMapFs) List

                                                                      func (m *MemMapFs) List()

                                                                      func (*MemMapFs) LstatIfPossible

                                                                      func (m *MemMapFs) LstatIfPossible(name string) (os.FileInfo, bool, error)

                                                                      func (*MemMapFs) Mkdir

                                                                      func (m *MemMapFs) Mkdir(name string, perm os.FileMode) error

                                                                      func (*MemMapFs) MkdirAll

                                                                      func (m *MemMapFs) MkdirAll(path string, perm os.FileMode) error

                                                                      func (*MemMapFs) Name

                                                                      func (*MemMapFs) Name() string

                                                                      func (*MemMapFs) Open

                                                                      func (m *MemMapFs) Open(name string) (File, error)

                                                                      func (*MemMapFs) OpenFile

                                                                      func (m *MemMapFs) OpenFile(name string, flag int, perm os.FileMode) (File, error)

                                                                      func (*MemMapFs) Remove

                                                                      func (m *MemMapFs) Remove(name string) error

                                                                      func (*MemMapFs) RemoveAll

                                                                      func (m *MemMapFs) RemoveAll(path string) error

                                                                      func (*MemMapFs) Rename

                                                                      func (m *MemMapFs) Rename(oldname, newname string) error

                                                                      func (*MemMapFs) Stat

                                                                      func (m *MemMapFs) Stat(name string) (os.FileInfo, error)

                                                                      type OsFs

                                                                      type OsFs struct{}

                                                                        OsFs is a Fs implementation that uses functions provided by the os package.

                                                                        For details in any method, check the documentation of the os package (http://golang.org/pkg/os/).

                                                                        func (OsFs) Chmod

                                                                        func (OsFs) Chmod(name string, mode os.FileMode) error

                                                                        func (OsFs) Chown

                                                                        func (OsFs) Chown(name string, uid, gid int) error

                                                                        func (OsFs) Chtimes

                                                                        func (OsFs) Chtimes(name string, atime time.Time, mtime time.Time) error

                                                                        func (OsFs) Create

                                                                        func (OsFs) Create(name string) (File, error)

                                                                        func (OsFs) LstatIfPossible

                                                                        func (OsFs) LstatIfPossible(name string) (os.FileInfo, bool, error)

                                                                        func (OsFs) Mkdir

                                                                        func (OsFs) Mkdir(name string, perm os.FileMode) error

                                                                        func (OsFs) MkdirAll

                                                                        func (OsFs) MkdirAll(path string, perm os.FileMode) error

                                                                        func (OsFs) Name

                                                                        func (OsFs) Name() string

                                                                        func (OsFs) Open

                                                                        func (OsFs) Open(name string) (File, error)

                                                                        func (OsFs) OpenFile

                                                                        func (OsFs) OpenFile(name string, flag int, perm os.FileMode) (File, error)

                                                                        func (OsFs) ReadlinkIfPossible

                                                                        func (OsFs) ReadlinkIfPossible(name string) (string, error)

                                                                        func (OsFs) Remove

                                                                        func (OsFs) Remove(name string) error

                                                                        func (OsFs) RemoveAll

                                                                        func (OsFs) RemoveAll(path string) error

                                                                        func (OsFs) Rename

                                                                        func (OsFs) Rename(oldname, newname string) error

                                                                        func (OsFs) Stat

                                                                        func (OsFs) Stat(name string) (os.FileInfo, error)

                                                                        func (OsFs) SymlinkIfPossible

                                                                        func (OsFs) SymlinkIfPossible(oldname, newname string) error

                                                                        type ReadOnlyFs

                                                                        type ReadOnlyFs struct {
                                                                        	// contains filtered or unexported fields
                                                                        }

                                                                        func (*ReadOnlyFs) Chmod

                                                                        func (r *ReadOnlyFs) Chmod(n string, m os.FileMode) error

                                                                        func (*ReadOnlyFs) Chown

                                                                        func (r *ReadOnlyFs) Chown(n string, uid, gid int) error

                                                                        func (*ReadOnlyFs) Chtimes

                                                                        func (r *ReadOnlyFs) Chtimes(n string, a, m time.Time) error

                                                                        func (*ReadOnlyFs) Create

                                                                        func (r *ReadOnlyFs) Create(n string) (File, error)

                                                                        func (*ReadOnlyFs) LstatIfPossible

                                                                        func (r *ReadOnlyFs) LstatIfPossible(name string) (os.FileInfo, bool, error)

                                                                        func (*ReadOnlyFs) Mkdir

                                                                        func (r *ReadOnlyFs) Mkdir(n string, p os.FileMode) error

                                                                        func (*ReadOnlyFs) MkdirAll

                                                                        func (r *ReadOnlyFs) MkdirAll(n string, p os.FileMode) error

                                                                        func (*ReadOnlyFs) Name

                                                                        func (r *ReadOnlyFs) Name() string

                                                                        func (*ReadOnlyFs) Open

                                                                        func (r *ReadOnlyFs) Open(n string) (File, error)

                                                                        func (*ReadOnlyFs) OpenFile

                                                                        func (r *ReadOnlyFs) OpenFile(name string, flag int, perm os.FileMode) (File, error)

                                                                        func (*ReadOnlyFs) ReadDir

                                                                        func (r *ReadOnlyFs) ReadDir(name string) ([]os.FileInfo, error)

                                                                        func (*ReadOnlyFs) ReadlinkIfPossible

                                                                        func (r *ReadOnlyFs) ReadlinkIfPossible(name string) (string, error)

                                                                        func (*ReadOnlyFs) Remove

                                                                        func (r *ReadOnlyFs) Remove(n string) error

                                                                        func (*ReadOnlyFs) RemoveAll

                                                                        func (r *ReadOnlyFs) RemoveAll(p string) error

                                                                        func (*ReadOnlyFs) Rename

                                                                        func (r *ReadOnlyFs) Rename(o, n string) error

                                                                        func (*ReadOnlyFs) Stat

                                                                        func (r *ReadOnlyFs) Stat(name string) (os.FileInfo, error)

                                                                        func (*ReadOnlyFs) SymlinkIfPossible

                                                                        func (r *ReadOnlyFs) SymlinkIfPossible(oldname, newname string) error

                                                                        type RegexpFile

                                                                        type RegexpFile struct {
                                                                        	// contains filtered or unexported fields
                                                                        }

                                                                        func (*RegexpFile) Close

                                                                        func (f *RegexpFile) Close() error

                                                                        func (*RegexpFile) Name

                                                                        func (f *RegexpFile) Name() string

                                                                        func (*RegexpFile) Read

                                                                        func (f *RegexpFile) Read(s []byte) (int, error)

                                                                        func (*RegexpFile) ReadAt

                                                                        func (f *RegexpFile) ReadAt(s []byte, o int64) (int, error)

                                                                        func (*RegexpFile) Readdir

                                                                        func (f *RegexpFile) Readdir(c int) (fi []os.FileInfo, err error)

                                                                        func (*RegexpFile) Readdirnames

                                                                        func (f *RegexpFile) Readdirnames(c int) (n []string, err error)

                                                                        func (*RegexpFile) Seek

                                                                        func (f *RegexpFile) Seek(o int64, w int) (int64, error)

                                                                        func (*RegexpFile) Stat

                                                                        func (f *RegexpFile) Stat() (os.FileInfo, error)

                                                                        func (*RegexpFile) Sync

                                                                        func (f *RegexpFile) Sync() error

                                                                        func (*RegexpFile) Truncate

                                                                        func (f *RegexpFile) Truncate(s int64) error

                                                                        func (*RegexpFile) Write

                                                                        func (f *RegexpFile) Write(s []byte) (int, error)

                                                                        func (*RegexpFile) WriteAt

                                                                        func (f *RegexpFile) WriteAt(s []byte, o int64) (int, error)

                                                                        func (*RegexpFile) WriteString

                                                                        func (f *RegexpFile) WriteString(s string) (int, error)

                                                                        type RegexpFs

                                                                        type RegexpFs struct {
                                                                        	// contains filtered or unexported fields
                                                                        }

                                                                          The RegexpFs filters files (not directories) by regular expression. Only files matching the given regexp will be allowed, all others get a ENOENT error ( "No such file or directory").

                                                                          func (*RegexpFs) Chmod

                                                                          func (r *RegexpFs) Chmod(name string, mode os.FileMode) error

                                                                          func (*RegexpFs) Chown

                                                                          func (r *RegexpFs) Chown(name string, uid, gid int) error

                                                                          func (*RegexpFs) Chtimes

                                                                          func (r *RegexpFs) Chtimes(name string, a, m time.Time) error

                                                                          func (*RegexpFs) Create

                                                                          func (r *RegexpFs) Create(name string) (File, error)

                                                                          func (*RegexpFs) Mkdir

                                                                          func (r *RegexpFs) Mkdir(n string, p os.FileMode) error

                                                                          func (*RegexpFs) MkdirAll

                                                                          func (r *RegexpFs) MkdirAll(n string, p os.FileMode) error

                                                                          func (*RegexpFs) Name

                                                                          func (r *RegexpFs) Name() string

                                                                          func (*RegexpFs) Open

                                                                          func (r *RegexpFs) Open(name string) (File, error)

                                                                          func (*RegexpFs) OpenFile

                                                                          func (r *RegexpFs) OpenFile(name string, flag int, perm os.FileMode) (File, error)

                                                                          func (*RegexpFs) Remove

                                                                          func (r *RegexpFs) Remove(name string) error

                                                                          func (*RegexpFs) RemoveAll

                                                                          func (r *RegexpFs) RemoveAll(p string) error

                                                                          func (*RegexpFs) Rename

                                                                          func (r *RegexpFs) Rename(oldname, newname string) error

                                                                          func (*RegexpFs) Stat

                                                                          func (r *RegexpFs) Stat(name string) (os.FileInfo, error)

                                                                          type Symlinker

                                                                          type Symlinker interface {
                                                                          	Lstater
                                                                          	Linker
                                                                          	LinkReader
                                                                          }

                                                                            Symlinker is an optional interface in Afero. It is only implemented by the filesystems saying so. It indicates support for 3 symlink related interfaces that implement the behaviors of the os methods:

                                                                            - Lstat
                                                                            - Symlink, and
                                                                            - Readlink
                                                                            

                                                                            type UnionFile

                                                                            type UnionFile struct {
                                                                            	Base   File
                                                                            	Layer  File
                                                                            	Merger DirsMerger
                                                                            	// contains filtered or unexported fields
                                                                            }

                                                                              The UnionFile implements the afero.File interface and will be returned when reading a directory present at least in the overlay or opening a file for writing.

                                                                              The calls to Readdir() and Readdirnames() merge the file os.FileInfo / names from the base and the overlay - for files present in both layers, only those from the overlay will be used.

                                                                              When opening files for writing (Create() / OpenFile() with the right flags) the operations will be done in both layers, starting with the overlay. A successful read in the overlay will move the cursor position in the base layer by the number of bytes read.

                                                                              func (*UnionFile) Close

                                                                              func (f *UnionFile) Close() error

                                                                              func (*UnionFile) Name

                                                                              func (f *UnionFile) Name() string

                                                                              func (*UnionFile) Read

                                                                              func (f *UnionFile) Read(s []byte) (int, error)

                                                                              func (*UnionFile) ReadAt

                                                                              func (f *UnionFile) ReadAt(s []byte, o int64) (int, error)

                                                                              func (*UnionFile) Readdir

                                                                              func (f *UnionFile) Readdir(c int) (ofi []os.FileInfo, err error)

                                                                                Readdir will weave the two directories together and return a single view of the overlayed directories. At the end of the directory view, the error is io.EOF if c > 0.

                                                                                func (*UnionFile) Readdirnames

                                                                                func (f *UnionFile) Readdirnames(c int) ([]string, error)

                                                                                func (*UnionFile) Seek

                                                                                func (f *UnionFile) Seek(o int64, w int) (pos int64, err error)

                                                                                func (*UnionFile) Stat

                                                                                func (f *UnionFile) Stat() (os.FileInfo, error)

                                                                                func (*UnionFile) Sync

                                                                                func (f *UnionFile) Sync() (err error)

                                                                                func (*UnionFile) Truncate

                                                                                func (f *UnionFile) Truncate(s int64) (err error)

                                                                                func (*UnionFile) Write

                                                                                func (f *UnionFile) Write(s []byte) (n int, err error)

                                                                                func (*UnionFile) WriteAt

                                                                                func (f *UnionFile) WriteAt(s []byte, o int64) (n int, err error)

                                                                                func (*UnionFile) WriteString

                                                                                func (f *UnionFile) WriteString(s string) (n int, err error)

                                                                                Directories

                                                                                Path Synopsis
                                                                                package tarfs implements a read-only in-memory representation of a tar archive
                                                                                package tarfs implements a read-only in-memory representation of a tar archive