github.com/3JoB/vfs@v1.0.0/README.md (about)

     1  vfs for golang [![Build Status](https://travis-ci.org/blang/vfs.svg?branch=master)](https://travis-ci.org/blang/vfs) [![GoDoc](https://godoc.org/github.com/3JoB/vfs?status.png)](https://godoc.org/github.com/3JoB/vfs) [![Coverage Status](https://img.shields.io/coveralls/blang/vfs.svg)](https://coveralls.io/r/blang/vfs?branch=master) [![Join the chat at https://gitter.im/blang/vfs](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/blang/vfs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
     2  ======
     3  
     4  vfs is library to support virtual filesystems. It provides basic abstractions of filesystems and implementations, like `OS` accessing the file system of the underlying OS and `memfs` a full filesystem in-memory.
     5  
     6  Usage
     7  -----
     8  ```bash
     9  $ go get github.com/3JoB/vfs
    10  ```
    11  Note: Always vendor your dependencies or fix on a specific version tag.
    12  
    13  ```go
    14  import github.com/3JoB/vfs
    15  ```
    16  
    17  ```go
    18  // Create a vfs accessing the filesystem of the underlying OS
    19  var osfs vfs.Filesystem = vfs.OS()
    20  osfs.Mkdir("/tmp", 0777)
    21  
    22  // Make the filesystem read-only:
    23  osfs = vfs.ReadOnly(osfs) // Simply wrap filesystems to change its behaviour
    24  
    25  // os.O_CREATE will fail and return vfs.ErrReadOnly
    26  // os.O_RDWR is supported but Write(..) on the file is disabled
    27  f, _ := osfs.OpenFile("/tmp/example.txt", os.O_RDWR, 0)
    28  
    29  // Return vfs.ErrReadOnly
    30  _, err := f.Write([]byte("Write on readonly fs?"))
    31  if err != nil {
    32      fmt.Errorf("Filesystem is read only!\n")
    33  }
    34  
    35  // Create a fully writable filesystem in memory
    36  mfs := memfs.Create()
    37  mfs.Mkdir("/root", 0777)
    38  
    39  // Create a vfs supporting mounts
    40  // The root fs is accessing the filesystem of the underlying OS
    41  fs := mountfs.Create(osfs)
    42  
    43  // Mount a memfs inside /memfs
    44  // /memfs may not exist
    45  fs.Mount(mfs, "/memfs")
    46  
    47  // This will create /testdir inside the memfs
    48  fs.Mkdir("/memfs/testdir", 0777)
    49  
    50  // This would create /tmp/testdir inside your OS fs
    51  // But the rootfs `osfs` is read-only
    52  fs.Mkdir("/tmp/testdir", 0777)
    53  ```
    54  
    55  Check detailed examples below. Also check the [GoDocs](http://godoc.org/github.com/3JoB/vfs).
    56  
    57  Why should I use this lib?
    58  -----
    59  
    60  - Only Stdlib
    61  - (Nearly) Fully tested (Coverage >90%)
    62  - Easy to create your own filesystem
    63  - Mock a full filesystem for testing (or use included `memfs`)
    64  - Compose/Wrap Filesystems `ReadOnly(OS())` and write simple Wrappers
    65  - Many features, see [GoDocs](http://godoc.org/github.com/3JoB/vfs) and examples below
    66  
    67  Features and Examples
    68  -----
    69  
    70  - [OS Filesystem support](http://godoc.org/github.com/3JoB/vfs#example-OsFS)
    71  - [ReadOnly Wrapper](http://godoc.org/github.com/3JoB/vfs#example-RoFS)
    72  - [DummyFS for quick mocking](http://godoc.org/github.com/3JoB/vfs#example-DummyFS)
    73  - [MemFS - full in-memory filesystem](http://godoc.org/github.com/3JoB/vfs/memfs#example-MemFS)
    74  - [MountFS - support mounts across filesystems](http://godoc.org/github.com/3JoB/vfs/mountfs#example-MountFS)
    75  
    76  Current state: ALPHA
    77  -----
    78  
    79  While the functionality is quite stable and heavily tested, interfaces are subject to change. 
    80  
    81      You need more/less abstraction? Let me know by creating a Issue, thank you.
    82  
    83  Motivation
    84  -----
    85  
    86  I simply couldn't find any lib supporting this wide range of variation and adaptability.
    87  
    88  Contribution
    89  -----
    90  
    91  Feel free to make a pull request. For bigger changes create a issue first to discuss about it.
    92  
    93  License
    94  -----
    95  
    96  See [LICENSE](LICENSE) file.