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 ```