README.md
1# go-billy [![GoDoc](https://godoc.org/gopkg.in/src-d/go-billy.v4?status.svg)](https://godoc.org/gopkg.in/src-d/go-billy.v4) [![Build Status](https://travis-ci.org/src-d/go-billy.svg)](https://travis-ci.org/src-d/go-billy) [![Build status](https://ci.appveyor.com/api/projects/status/vx2qn6vlakbi724t?svg=true)](https://ci.appveyor.com/project/mcuadros/go-billy) [![codecov](https://codecov.io/gh/src-d/go-billy/branch/master/graph/badge.svg)](https://codecov.io/gh/src-d/go-billy)
2
3The missing interface filesystem abstraction for Go.
4Billy implements an interface based on the `os` standard library, allowing to develop applications without dependency on the underlying storage. Makes it virtually free to implement mocks and testing over filesystem operations.
5
6Billy was born as part of [src-d/go-git](https://github.com/src-d/go-git) project.
7
8## Installation
9
10```go
11go get -u gopkg.in/src-d/go-billy.v4/...
12```
13
14## Usage
15
16Billy exposes filesystems using the
17[`Filesystem` interface](https://godoc.org/github.com/src-d/go-billy#Filesystem).
18Each filesystem implementation gives you a `New` method, whose arguments depend on
19the implementation itself, that returns a new `Filesystem`.
20
21The following example caches in memory all readable files in a directory from any
22billy's filesystem implementation.
23
24```go
25func LoadToMemory(origin billy.Filesystem, path string) (*memory.Memory, error) {
26 memory := memory.New()
27
28 files, err := origin.ReadDir("/")
29 if err != nil {
30 return nil, err
31 }
32
33 for _, file := range files {
34 if file.IsDir() {
35 continue
36 }
37
38 src, err := origin.Open(file.Name())
39 if err != nil {
40 return nil, err
41 }
42
43 dst, err := memory.Create(file.Name())
44 if err != nil {
45 return nil, err
46 }
47
48 if _, err = io.Copy(dst, src); err != nil {
49 return nil, err
50 }
51
52 if err := dst.Close(); err != nil {
53 return nil, err
54 }
55
56 if err := src.Close(); err != nil {
57 return nil, err
58 }
59 }
60
61 return memory, nil
62}
63```
64
65## Why billy?
66
67The library billy deals with storage systems and Billy is the name of a well-known, IKEA
68bookcase. That's it.
69
70## License
71
72Apache License Version 2.0, see [LICENSE](LICENSE)
73