github.com/IBM/fsgo@v0.0.0-20220920202152-e16fd2119d49/README.md (about)

     1  # fsgo
     2  
     3  <!-- Build Status, is a great thing to have at the top of your repository, it shows that you take your CI/CD as first class citizens -->
     4  <!-- [![Build Status](https://travis-ci.org/jjasghar/ibm-cloud-cli.svg?branch=master)](https://travis-ci.org/jjasghar/ibm-cloud-cli) -->
     5  
     6  ## Scope
     7  
     8  A FileSystem Abstraction System for Go, based on the package [Afero](https://github.com/spf13/afero). This project is a subset of the functionality of Fsgo that eliminates the use of the crypto dependency. The Fsgo project includes concrete implementations of the abstraction that support multiple filesystems that are not needed for unit testing in a secure environment.
     9  
    10  Fsgo is a filesystem framework providing a simple, uniform and universal API
    11  interacting with any filesystem, as an abstraction layer providing interfaces,
    12  types and methods. Fsgo has an exceptionally clean interface and simple design
    13  without needless constructors or initialization methods.
    14  
    15  Fsgo is also a library providing a base set of interoperable backend
    16  filesystems that make it easy to work with fsgo while retaining all the power
    17  and benefit of the os and ioutil packages.
    18  
    19  Fsgo provides significant improvements over using the os package alone, most
    20  notably the ability to create mock and testing filesystems without relying on the disk.
    21  
    22  It is suitable for use in any situation where you would consider using the OS
    23  package as it provides an additional abstraction that makes it easy to use a
    24  memory backed file system during testing. It also adds support for the http
    25  filesystem for full interoperability.
    26  
    27  ## Fsgo Features
    28  
    29  * A single consistent API for accessing a variety of filesystems
    30  * Interoperation between a variety of file system types
    31  * A set of interfaces to encourage and enforce interoperability between backends
    32  * An atomic cross platform memory backed file system
    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)
    35  * A set of utility functions ported from io, ioutil & hugo to be fsgo aware
    36  * Wrapper for go 1.16 filesystem abstraction `io/fs.FS`
    37  
    38  # Using Fsgo
    39  
    40  Fsgo is easy to use and easier to adopt.
    41  
    42  A few different ways you could use Fsgo:
    43  
    44  * Use the interfaces alone to define your own file system.
    45  * Wrapper for the OS packages.
    46  * Define different filesystems for different parts of your application.
    47  * Use Fsgo for mock filesystems while testing
    48  
    49  ## Step 1: Install Fsgo
    50  
    51  First use go get to install the latest version of the library.
    52  
    53      $ go get github.com/IBM/fsgo
    54  
    55  Next include Fsgo in your application.
    56  ```go
    57  import "github.com/IBM/fsgo"
    58  ```
    59  
    60  ## Step 2: Declare a backend
    61  
    62  First define a package variable and set it to a pointer to a filesystem.
    63  ```go
    64  var AppFs = fsgo.NewMemMapFs()
    65  
    66  or
    67  
    68  var AppFs = fsgo.NewOsFs()
    69  ```
    70  It is important to note that if you repeat the composite literal you
    71  will be using a completely new and isolated filesystem. In the case of
    72  OsFs it will still use the same underlying filesystem but will reduce
    73  the ability to drop in other filesystems as desired.
    74  
    75  ## Step 3: Use it like you would the OS package
    76  
    77  Throughout your application use any function and method like you normally
    78  would.
    79  
    80  So if my application before had:
    81  ```go
    82  os.Open("/tmp/foo")
    83  ```
    84  We would replace it with:
    85  ```go
    86  AppFs.Open("/tmp/foo")
    87  ```
    88  
    89  `AppFs` being the variable we defined above.
    90  
    91  ## Notes
    92  
    93  **NOTE: This repository has been configured with the [DCO bot](https://github.com/probot/dco).
    94  When you set up a new repository that uses the Apache license, you should
    95  use the DCO to manage contributions. The DCO bot will help enforce that.
    96  Please contact one of the IBM GH Org stewards.**
    97  
    98  <!-- Questions can be useful but optional, this gives you a place to say, "This is how to contact this project maintainers or create PRs -->
    99  If you have any questions or issues you can create a new [issue here][issues].
   100  
   101  Pull requests are very welcome! Make sure your patches are well tested.
   102  Ideally create a topic branch for every separate change you make. For
   103  example:
   104  
   105  1. Fork the repo
   106  2. Create your feature branch (`git checkout -b my-new-feature`)
   107  3. Commit your changes (`git commit -am 'Added some feature'`)
   108  4. Push to the branch (`git push origin my-new-feature`)
   109  5. Create new Pull Request
   110  
   111  ## License
   112  
   113  All source files must include a Copyright and License header. The SPDX license header is 
   114  preferred because it can be easily scanned.
   115  
   116  If you would like to see the detailed LICENSE click [here](LICENSE).
   117  
   118  ```text
   119  #
   120  # Copyright 2020- IBM Inc. All rights reserved
   121  # SPDX-License-Identifier: Apache2.0
   122  #
   123  ```