Afero

https://github.com/spf13/afero
Admin
Afero is a filesystem abstraction library for Go that works as a drop-in replacement for the...
Tokens:49,695
Snippets:556
Trust Score:9.9
License:Apache-2.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### OsFs Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/osfs-memfs.md

Demonstrates how to use the OsFs implementation to read a configuration file. This example uses the real OS filesystem for file operations.

```go
package main

import (
    "github.com/spf13/afero"
    "log"
    "os"
)

func ProcessConfiguration(fs afero.Fs, path string) error {
    // Use the fs abstraction
    data, err := afero.ReadFile(fs, path)
    if err != nil {
        return err
    }

    // Process data...
    log.Println("Loaded config:", string(data))
    return nil
}

func main() {
    // In production: use the real OS filesystem
    fs := afero.NewOsFs()

    if err := ProcessConfiguration(fs, "config.json"); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Basic Afero Filesystem Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/README.md

Demonstrates the fundamental usage of Afero, including creating an in-memory filesystem, writing a file, reading it back, listing directory contents, and walking the directory tree. This example is suitable for understanding the core API.

```go
func main() {
    // Choose filesystem
    fs := afero.NewMemMapFs()  // or NewOsFs() in production
    
    // Write a file
    afero.WriteFile(fs, "config.json", []byte(`{"key":"value"}`), 0o644)
    
    // Read it back
    data, _ := afero.ReadFile(fs, "config.json")
    
    // List directory
    files, _ := afero.ReadDir(fs, ".")
    
    // Walk tree
    afero.Walk(fs, ".", func(path string, info os.FileInfo, err error) error {
        return nil
    })
}
```

--------------------------------

### Install Afero Go Package

Source: https://github.com/spf13/afero/blob/master/README.md

Use 'go get' to install the Afero library. This command fetches and installs the specified package and its dependencies.

```bash
go get github.com/spf13/afero
```

--------------------------------

### Usage Example for BasePathFs

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/composite-filesystems.md

Demonstrates how to create a sandboxed filesystem using BasePathFs. This example shows successful creation of files within the base path and prevention of attempts to access files outside it.

```go
package main

import (
    "github.com/spf13/afero"
    "log"
)

func main() {
    // Create a real filesystem and restrict to /app directory
    osfs := afero.NewOsFs()
    sandboxed := afero.NewBasePathFs(osfs, "/app")

    // This works
    sandboxed.Create("config.txt")  // Creates /app/config.txt

    // This is prevented
    file, err := sandboxed.Create("../../../etc/passwd")  // Error: os.ErrNotExist
    if err != nil {
        log.Println("Blocked escape attempt:", err)
    }

    // Access to /app subdirectories is fine
    sandboxed.Mkdir("subdir", 0o755)
    sandboxed.Create("subdir/data.txt")  // Creates /app/subdir/data.txt
}
```

--------------------------------

### Valid Paths Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

Demonstrates examples of valid paths that the IOFS adapter accepts.

```go
"."
```

```go
"dir/file.txt"
```

```go
"dir/subdir/file.txt"
```

```go
"file with spaces.txt"
```

--------------------------------

### OsFs Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/osfs-memfs.md

Demonstrates how to use the OsFs filesystem implementation with the afero abstraction to process configuration files.

```APIDOC
## Usage Example

### Description
This example shows how to initialize `OsFs` and use it with the `afero` library to read a configuration file.

### Code
```go
package main

import (
    "github.com/spf13/afero"
    "log"
    "os"
)

func ProcessConfiguration(fs afero.Fs, path string) error {
    // Use the fs abstraction
    data, err := afero.ReadFile(fs, path)
    if err != nil {
        return err
    }

    // Process data...
    log.Println("Loaded config:", string(data))
    return nil
}

func main() {
    // In production: use the real OS filesystem
    fs := afero.NewOsFs()

    if err := ProcessConfiguration(fs, "config.json"); err != nil {
        log.Fatal(err)
    }
}
```
```

--------------------------------

### HttpFs Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/archive-filesystems.md

Demonstrates how to create an in-memory filesystem, populate it with files, wrap it with HttpFs, and serve it over HTTP. Ensure the necessary packages are imported.

```go
package main

import (
    "github.com/spf13/afero"
    "log"
    "net/http"
)

func main() {
    // Create in-memory filesystem with some files
    fs := afero.NewMemMapFs()
    afero.WriteFile(fs, "/index.html", []byte("<h1>Hello</h1>"), 0o644)
    afero.WriteFile(fs, "/style.css", []byte("body { color: blue; }"), 0o644)

    // Wrap for HTTP serving
    httpFs := afero.NewHttpFs(fs)

    // Serve at root
    http.Handle("/", http.FileServer(httpFs.Dir("/")))

    log.Println("Serving on :8080")
    http.ListenAndServe(":8080", nil)
}
```

--------------------------------

### Combined Example: Multi-Archive Access

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/archive-filesystems.md

This example demonstrates how to open and list contents of both ZIP and TAR archives as afero filesystems. It requires the archive files 'data.zip' and 'data.tar' to be present in the same directory.

```go
package main

import (
    "archive/tar"
    "archive/zip"
    "github.com/spf13/afero"
    "github.com/spf13/afero/tarfs"
    "github.com/spf13/afero/zipfs"
    "log"
    "os"
)

func listArchiveContents(fs afero.Fs, path string) error {
    files, err := afero.ReadDir(fs, path)
    if err != nil {
        return err
    }
    for _, f := range files {
        log.Printf("%s (%d bytes)\n", f.Name(), f.Size())
    }
    return nil
}

func main() {
    // Open ZIP file
    zipFile, _ := os.Open("data.zip")
    defer zipFile.Close()
    fi, _ := zipFile.Stat()
    reader, _ := zip.NewReader(zipFile, fi.Size())
    zfs := zipfs.New(reader)

    // Open TAR file
    tarFile, _ := os.Open("data.tar")
    defer tarFile.Close()
    tfs := tarfs.New(tar.NewReader(tarFile))

    // Work with both
    log.Println("ZIP contents:")
    listArchiveContents(zfs, "/")

    log.Println("\nTAR contents:")
    listArchiveContents(tfs, "/")
}
```

--------------------------------

### Walk Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/utility-functions.md

Demonstrates how to use the Walk function to traverse a directory and log the paths of all files encountered. Ensure the WalkFunc handles potential errors.

```go
err := afero.Walk(fs, "/app", func(path string, info os.FileInfo, err error) error {
    if err != nil {
        return err
    }
    if !info.IsDir() {
        log.Println("File:", path)
    }
    return nil
})
```

--------------------------------

### Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/osfs-memfs.md

Demonstrates how to use MemMapFs for testing by creating and reading files, contrasting it with using the real filesystem (OsFs).

```APIDOC
## Usage Example

### Description
This example shows how to utilize `MemMapFs` for testing purposes, allowing for isolated and fast file operations without interacting with the actual disk. It also includes a comparison with `OsFs` for context.

### Code
```go
package main

import (
    "github.com/spf13/afero"
    "log"
    "os"
)

func CreateConfigFile(fs afero.Fs) error {
    data := []byte("key=value\nfoo=bar")
    return afero.WriteFile(fs, "/app/config.txt", data, 0o644)
}

func TestWithMemFs() {
    // Use in-memory filesystem for testing
    fs := afero.NewMemMapFs()

    if err := CreateConfigFile(fs); err != nil {
        log.Fatal(err)
    }

    content, _ := afero.ReadFile(fs, "/app/config.txt")
    log.Println("Loaded:", string(content))
}

func TestWithRealFs() {
    // Use real filesystem in production
    fs := afero.NewOsFs()

    if err := CreateConfigFile(fs); err != nil {
        log.Fatal(err)
    }

    content, _ := afero.ReadFile(fs, "/app/config.txt")
    log.Println("Loaded:", string(content))
}

func main() {
    TestWithMemFs()
    TestWithRealFs()
}
```
```

--------------------------------

### ReadOnlyFs Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/composite-filesystems.md

Demonstrates creating a read-only filesystem, reading from it successfully, and attempting to write, which is blocked.

```go
package main

import (
    "github.com/spf13/afero"
    "log"
)

func main() {
    base := afero.NewMemMapFs()
    afero.WriteFile(base, "config.txt", []byte("data"), 0o644)

    // Create read-only wrapper
    readonly := afero.NewReadOnlyFs(base)

    // Reading works
    data, _ := afero.ReadFile(readonly, "config.txt")
    log.Println("Read:", string(data))

    // Writing fails
    err := afero.WriteFile(readonly, "new.txt", []byte("fail"), 0o644)
    if err != nil {
        log.Println("Write blocked:", err)
    }
}
```

--------------------------------

### Usage Example: IOFS with Standard Library

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

Demonstrates creating an Afero filesystem, adapting it to io/fs, and then using standard library functions like ReadFile and fs.WalkDir.

```go
package main

import (
    "github.com/spf13/afero"
    "io/fs"
    "log"
)

func main() {
    // Create an Afero filesystem
    afs := afero.NewMemMapFs()
    afero.WriteFile(afs, "README.md", []byte("# Documentation"), 0o644)

    // Adapt to io/fs
    iofs := afero.NewIOFS(afs)

    // Now use with standard library functions
    content, err := iofs.ReadFile("README.md")
    if err != nil {
        log.Fatal(err)
    }
    log.Println(string(content))

    // Walk using standard library
    fs.WalkDir(iofs, ".", func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if !d.IsDir() {
            log.Println("File:", path)
        }
        return nil
    })
}
```

--------------------------------

### Layered Filesystem Composition Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/patterns-and-architecture.md

Demonstrates stacking multiple filesystem implementations like `BasePathFs`, `ReadOnlyFs`, and `RegexpFs` on top of a base `MemMapFs` to create a composed filesystem with specific behaviors.

```go
// Create base filesystem
base := afero.NewMemMapFs()

// Layer 1: Restrict to /app directory
sandboxed := afero.NewBasePathFs(base, "/app")

// Layer 2: Make it read-only
secure := afero.NewReadOnlyFs(sandboxed)

// Layer 3: Filter to config files only
configOnly := afero.NewRegexpFs(secure, regexp.MustCompile(`\.conf$`))

// Use the composed filesystem
data, _ := afero.ReadFile(configOnly, "app.conf")
```

--------------------------------

### filepath/filepath.WalkDir Integration

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

Example of using filepath/filepath.WalkDir with an Afero filesystem adapted to io/fs.

```go
import (
    "fs"
    "github.com/spf13/afero"
)

func main() {
    afs := afero.NewMemMapFs()
    iofs := afero.NewIOFS(afs)

    fs.WalkDir(iofs, ".", func(path string, d fs.DirEntry, err error) error {
        // Process entries
        return nil
    })
}
```

--------------------------------

### RegexpFs Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/composite-filesystems.md

Demonstrates how to use RegexpFs to filter files. This example creates an in-memory filesystem, adds files, and then applies a regex filter to only allow '.txt' files. It shows successful reading of a matching file and the error received when attempting to read a non-matching file.

```go
package main

import (
    "github.com/spf13/afero"
    "log"
    "regexp"
)

func main() {
    fs := afero.NewMemMapFs()
    afero.WriteFile(fs, "doc1.txt", []byte("doc"), 0o644)
    afero.WriteFile(fs, "image.jpg", []byte("image"), 0o644)
    afero.WriteFile(fs, "readme.md", []byte("readme"), 0o644)

    // Filter to only .txt files
    txtOnly := afero.NewRegexpFs(fs, regexp.MustCompile(`\.txt$`))

    // Can read .txt files
    data, _ := afero.ReadFile(txtOnly, "doc1.txt")
    log.Println("Read txt:", string(data))

    // .jpg files appear not to exist
    _, err := afero.ReadFile(txtOnly, "image.jpg")
    if err != nil {
        log.Println("jpg blocked:", err)
    }

    // Directories are visible
    files, _ := afero.ReadDir(txtOnly, ".")
    log.Println("Files:", len(files))
}
```

--------------------------------

### HttpFs Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/archive-filesystems.md

Demonstrates how to use the HttpFs wrapper to serve files from an in-memory filesystem over HTTP.

```APIDOC
## Usage Example

```go
package main

import (
    "github.com/spf13/afero"
    "log"
    "net/http"
)

func main() {
    // Create in-memory filesystem with some files
    fs := afero.NewMemMapFs()
    afero.WriteFile(fs, "/index.html", []byte("<h1>Hello</h1>"), 0o644)
    afero.WriteFile(fs, "/style.css", []byte("body { color: blue; }"), 0o644)

    // Wrap for HTTP serving
    httpFs := afero.NewHttpFs(fs)

    // Serve at root
    http.Handle("/", http.FileServer(httpFs.Dir("/")))

    log.Println("Serving on :8080")
    http.ListenAndServe(":8080", nil)
}
```
```

--------------------------------

### Using IOFS Adapter with Standard Library

Source: https://github.com/spf13/afero/blob/master/_autodocs/types.md

Example demonstrating how to convert an Afero filesystem (e.g., `MemMapFs`) into an `io/fs.FS` using the `NewIOFS` constructor. This allows you to use standard library functions like `ReadFile` and `ReadDir` with your Afero filesystem.

```go
// Convert Afero Fs to io/fs.FS
afs := afero.NewMemMapFs()
iofs := afero.NewIOFS(afs)

// Now can use with stdlib functions
data, _ := iofs.ReadFile("config.json")
entries, _ := iofs.ReadDir(".")
```

--------------------------------

### Usage Example: Testing with MemMapFs and OsFs

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/osfs-memfs.md

Demonstrates how to use MemMapFs for testing by creating and reading a configuration file in memory. It also shows how to use OsFs for the same operation on the real filesystem. Ensure the 'github.com/spf13/afero' package is imported.

```go
package main

import (
    "github.com/spf13/afero"
    "log"
    "os"
)

func CreateConfigFile(fs afero.Fs) error {
    data := []byte("key=value\nfoo=bar")
    return afero.WriteFile(fs, "/app/config.txt", data, 0o644)
}

func TestWithMemFs() {
    // Use in-memory filesystem for testing
    fs := afero.NewMemMapFs()

    if err := CreateConfigFile(fs); err != nil {
        log.Fatal(err)
    }

    content, _ := afero.ReadFile(fs, "/app/config.txt")
    log.Println("Loaded:", string(content))
}

func TestWithRealFs() {
    // Use real filesystem in production
    fs := afero.NewOsFs()

    if err := CreateConfigFile(fs); err != nil {
        log.Fatal(err)
    }

    content, _ := afero.ReadFile(fs, "/app/config.txt")
    log.Println("Loaded:", string(content))
}

func main() {
    TestWithMemFs()
    TestWithRealFs()
}
```

--------------------------------

### Afero Fs Interface Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/core-interfaces.md

Demonstrates how to use the Afero Fs interface to create, write to, and read from a file using an in-memory filesystem. Ensure the Fs interface is imported.

```go
package main

import (
    "github.com/spf13/afero"
    "log"
)

func ProcessFiles(fs afero.Fs) error {
    // Create a file
    f, err := fs.Create("/test.txt")
    if err != nil {
        return err
    }
    defer f.Close()

    // Write to it
    if _, err := f.WriteString("Hello"); err != nil {
        return err
    }

    // Read it back
    data, err := afero.ReadFile(fs, "/test.txt")
    if err != nil {
        return err
    }
    log.Println(string(data))

    return nil
}

func main() {
    fs := afero.NewMemMapFs()
    ProcessFiles(fs)
}
```

--------------------------------

### CopyOnWriteFs Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/composite-filesystems.md

Demonstrates how to use CopyOnWriteFs to create a sandboxed filesystem. Files are read from the layer if present, otherwise from the base. Writes and modifications are always to the layer.

```go
package main

import (
    "github.com/spf13/afero"
)

func main() {
    // Base: a read-only in-memory filesystem with some files
    base := afero.NewMemMapFs()
    afero.WriteFile(base, "template.txt", []byte("Template"), 0o644)

    // Layer: another in-memory filesystem for modifications
    layer := afero.NewMemMapFs()

    // Create a copy-on-write filesystem
    cow := afero.NewCopyOnWriteFs(base, layer)

    // Read from base through cow
    content, _ := afero.ReadFile(cow, "template.txt")  // From base

    // Modify the file: it's copied to layer, then modified
    afero.WriteFile(cow, "template.txt", []byte("Modified"), 0o644)

    // Now reads come from layer
    modified, _ := afero.ReadFile(cow, "template.txt")  // From layer

    // Original base is untouched
    original, _ := afero.ReadFile(base, "template.txt")  // Still "Template"

    println("CowFs version:", string(modified))
    println("Base version:", string(original))
}
```

--------------------------------

### Implementing Caching with CacheOnReadFs and IOFS

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

This example demonstrates how to create a caching layer using `afero.NewCacheOnReadFs` and then wrap it with `afero.NewIOFS` to make it compatible with the `io/fs` interface. Reads will utilize the cache.

```go
// Create caching layer
baseFS := afero.NewMemMapFs()
cache := afero.NewMemMapFs()
cached := afero.NewCacheOnReadFs(baseFS, cache, 5*time.Minute)

// Wrap for io/fs compatibility
iofs := afero.NewIOFS(cached)

// Reads use cache
data, _ := iofs.ReadFile("file.txt")
```

--------------------------------

### BasePathFs Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/composite-filesystems.md

Demonstrates how to create and use a BasePathFs to sandbox filesystem operations, including preventing directory traversal.

```APIDOC
## Usage Example

### Description
This example shows how to create a sandboxed filesystem using `NewBasePathFs` and demonstrates successful operations within the base path as well as prevented attempts to escape it.

### Code
```go
package main

import (
    "github.com/spf13/afero"
    "log"
)

func main() {
    // Create a real filesystem and restrict to /app directory
    osfs := afero.NewOsFs()
    sandboxed := afero.NewBasePathFs(osfs, "/app")

    // This works
    sandboxed.Create("config.txt")  // Creates /app/config.txt

    // This is prevented
    file, err := sandboxed.Create("../../../etc/passwd")  // Error: os.ErrNotExist
    if err != nil {
        log.Println("Blocked escape attempt:", err)
    }

    // Access to /app subdirectories is fine
    sandboxed.Mkdir("subdir", 0o755)
    sandboxed.Create("subdir/data.txt")  // Creates /app/subdir/data.txt
}
```
```

--------------------------------

### WalkDir Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/utility-functions.md

Illustrates using WalkDir to iterate through a directory and log file paths. This method is preferred for performance due to its use of DirEntry.

```go
err := afero.WalkDir(fs, "/app", func(path string, entry fs.DirEntry, err error) error {
    if err != nil {
        return err
    }
    if !entry.IsDir() {
        log.Println("File:", path)
    }
    return nil
})
```

--------------------------------

### Usage Example: Reading and Walking TAR Archive

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/archive-filesystems.md

Demonstrates how to open a gzip-compressed TAR file, create a TarFs filesystem, read a specific file, and walk through the archive's directory structure.

```go
package main

import (
    "archive/tar"
    "compress/gzip"
    "github.com/spf13/afero"
    "github.com/spf13/afero/tarfs"
    "log"
    "os"
)

func main() {
    // Open a gzip-compressed TAR file
    file, err := os.Open("archive.tar.gz")
    if err != nil {
        log.Fatal(err)
    }
    defer file.Close()

    // Create gzip reader
    gzipReader, err := gzip.NewReader(file)
    if err != nil {
        log.Fatal(err)
    }
    defer gzipReader.Close()

    // Create TAR reader
    tarReader := tar.NewReader(gzipReader)

    // Create filesystem from TAR
    tfs := tarfs.New(tarReader)

    // Read files
    content, err := afero.ReadFile(tfs, "README.md")
    if err != nil {
        log.Fatal(err)
    }
    log.Println(string(content))

    // Walk through archive
    afero.Walk(tfs, "/", func(path string, info os.FileInfo, err error) error {
        if err == nil && !info.IsDir() {
            log.Println("File:", path)
        }
        return nil
    })
}
```

--------------------------------

### WriteFile Go Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/utility-functions.md

Writes data to a file, creating it if necessary. Creates file if it doesn't exist, truncates and overwrites if it exists. Returns error if write is incomplete.

```go
content := []byte("Hello, World!")
err := afero.WriteFile(fs, "output.txt", content, 0o644)
```

--------------------------------

### Reading Files with Afero

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

Use `afero.ReadFile` for direct file reading when not needing `io/fs` compatibility. This example shows reading from an `afero.Fs` instance.

```go
// os package: use afero directly
data, _ := afero.ReadFile(afs, "file.txt")
```

--------------------------------

### ReadFile Go Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/utility-functions.md

Reads the entire contents of a file. Preallocates buffer based on file size if available. Does not return io.EOF as error.

```go
data, err := afero.ReadFile(fs, "config.json")
if err != nil {
    return err
}
log.Println(string(data))
```

--------------------------------

### Invalid Paths Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

Illustrates paths that are considered invalid by the IOFS adapter's strict validation rules.

```go
"."           // Must be "."
```

```go
".."          // No parent traversal
```

```go
"/absolute"   // No absolute paths
```

```go
"dir/../.."   // No parent traversal
```

```go
"dir/./file"  // No dot segments
```

```go
"\\"          // No backslashes (even on Windows)
```

```go
"file\x00.txt" // No null bytes
```

--------------------------------

### CacheOnReadFs Usage Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/composite-filesystems.md

Demonstrates creating a caching filesystem. The first read fetches data from the slow base, subsequent reads within the cache time are served from the fast layer, and reads after expiration re-fetch from the base.

```go
package main

import (
    "github.com/spf13/afero"
    "time"
)

func main() {
    // Slow base: simulated network/remote filesystem
    slow := afero.NewMemMapFs()
    afero.WriteFile(slow, "data.txt", []byte("Remote data"), 0o644)

    // Fast cache: local memory
    fast := afero.NewMemMapFs()

    // Create caching layer with 5-second cache expiration
    cached := afero.NewCacheOnReadFs(slow, fast, 5*time.Second)

    // First read: fetches from slow, stores in fast
    data1, _ := afero.ReadFile(cached, "data.txt")

    // Second read (within 5 seconds): from fast cache
    data2, _ := afero.ReadFile(cached, "data.txt")

    // After 5 seconds, next read fetches from slow again
    time.Sleep(6 * time.Second)
    data3, _ := afero.ReadFile(cached, "data.txt")

    // Cached reads are much faster!
}
```

--------------------------------

### ReadDir Go Example

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/utility-functions.md

Reads directory contents and returns sorted file metadata. Automatically closes the directory handle. Returns entries sorted by name. Returns empty slice for empty directories.

```go
files, err := afero.ReadDir(fs, "/app/config")
if err != nil {
    return err
}
for _, f := range files {
    log.Printf("%s: %d bytes\n", f.Name(), f.Size())
}
```

--------------------------------

### Listing Directory Entries with io/fs

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

When working with `io/fs` compatible file systems, you can use `iofs.ReadDir` to get directory entries. These entries implement `fs.DirEntry`, which can be used with functions expecting `os.FileInfo`.

```go
// fmt.Printf with os.FileInfo: works with fs.DirEntry too
entries, _ := iofs.ReadDir(".")
for _, e := range entries {
    fmt.Println(e.Name())
}
```

--------------------------------

### Initialize MinIO Backend

Source: https://github.com/spf13/afero/blob/master/README.md

Create an Afero filesystem for MinIO object storage. This backend is S3-compatible and offers deduplication and optimization features. Requires a context and MinIO endpoint URL.

```go
import "github.com/cpyun/afero-minio"

minioFs := miniofs.NewMinioFs(ctx, "minio://endpoint/bucket")
```

--------------------------------

### Lstater Interface

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/core-interfaces.md

The Lstater interface provides a method to get file information without following symbolic links.

```APIDOC
## LstatIfPossible

### Description
Returns file info (without following symlinks), a boolean indicating if Lstat was used (true) vs Stat (false), and error.

### Signature
`LstatIfPossible(name string) (os.FileInfo, bool, error)`
```

--------------------------------

### Initialize Amazon S3 Backend

Source: https://github.com/spf13/afero/blob/master/README.md

Instantiate an Afero filesystem for Amazon S3 using the official AWS SDK for Go. Requires bucket name and AWS session.

```go
import "github.com/fclairamb/afero-s3"

s3fs := s3.NewFs(bucket, session)
```

--------------------------------

### Production Use of Afero Filesystem Abstraction

Source: https://github.com/spf13/afero/blob/master/_autodocs/README.md

Demonstrates how to use the `NewOsFs()` constructor for real filesystem operations in a production environment, after having tested the logic with an in-memory filesystem. This highlights the seamless transition between testing and production configurations.

```go
// Production use
func main() {
    fs := afero.NewOsFs()
    ProcessConfig(fs, "config.json")
}
```

--------------------------------

### Create New File with WriteFile

Source: https://github.com/spf13/afero/blob/master/_autodocs/errors.md

When creating new files, `WriteFile` is a convenient alternative to `Create` as it handles file creation and writing in one step, implicitly managing the file's existence.

```Go
afero.WriteFile(path, content, perm)
```

--------------------------------

### Logging Full Error Context with PathError

Source: https://github.com/spf13/afero/blob/master/_autodocs/errors.md

Provides an example of logging detailed context when a PathError occurs, including the operation, path, and underlying error.

```go
if pathErr, ok := err.(*os.PathError); ok {
    log.Printf("Failed to %s %s: %v", 
        pathErr.Op, pathErr.Path, pathErr.Err)
}
```

--------------------------------

### net/http.FileServer Integration

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

Shows how to serve Afero filesystems via HTTP using either HttpFs or the IOFS adapter with http.FileServer.

```go
import (
    "github.com/spf13/afero"
    "net/http"
)

func main() {
    afs := afero.NewMemMapFs()
    afero.WriteFile(afs, "index.html", []byte("<h1>Hello</h1>"), 0o644)

    // Method 1: Using HttpFs
    hfs := afero.NewHttpFs(afs)
    http.Handle("/", http.FileServer(hfs.Dir("/")))

    // Method 2: Using IOFS adapter
    iofs := afero.NewIOFS(afs)
    http.Handle("/", http.FileServer(iofs))

    http.ListenAndServe(":8080", nil)
}
```

--------------------------------

### Filesystem Abstraction vs. Direct OS Access

Source: https://github.com/spf13/afero/blob/master/_autodocs/patterns-and-architecture.md

Illustrates decoupling code from the `os` package by depending on the `afero.Fs` abstraction for improved testability and portability.

```go
// Instead of coupling to os package
func ProcessFile(filename string) error {
    data, err := os.ReadFile(filename)
    // ...
}

// Depend on abstraction
func ProcessFile(fs afero.Fs, filename string) error {
    data, err := afero.ReadFile(fs, filename)
    // ...
}
```

--------------------------------

### Afero Fs Implementations

Source: https://github.com/spf13/afero/blob/master/_autodocs/INDEX.md

Provides constructors for various filesystem implementations, including OS filesystem, in-memory, base path, copy-on-write, caching, read-only, regex-based, HTTP, zip, tar, and IOFS.

```go
NewOsFs() Fs
```

```go
NewMemMapFs() Fs
```

```go
NewBasePathFs(source Fs, path string) Fs
```

```go
NewCopyOnWriteFs(base, layer Fs) Fs
```

```go
NewCacheOnReadFs(base, layer Fs, cacheTime time.Duration) Fs
```

```go
NewReadOnlyFs(source Fs) Fs
```

```go
NewRegexpFs(source Fs, re *regexp.Regexp) Fs
```

```go
NewHttpFs(source Fs) *HttpFs
```

```go
zipfs.New(r *zip.Reader) afero.Fs
```

```go
tarfs.New(t *tar.Reader) *tarfs.Fs
```

```go
NewIOFS(fs Fs) IOFS
```

--------------------------------

### Using Afero Type Methods

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/core-interfaces.md

Demonstrates using the Afero type to call filesystem operations as methods, offering a more object-oriented approach.

```go
package main

import "github.com/spf13/afero"

func main() {
    fs := afero.NewMemMapFs()
    afs := afero.Afero{Fs: fs}

    // Use methods instead of package functions
    afs.WriteFile("config.txt", []byte("data"), 0o644)
    content, _ := afs.ReadFile("config.txt")
    println(string(content))
}
```

--------------------------------

### Use MemMapFs for In-Memory Testing

Source: https://github.com/spf13/afero/blob/master/README.md

For testing, inject `MemMapFs` to run your code entirely in memory without disk access. This requires no setup or cleanup and significantly speeds up test execution.

```go
func TestProcessConfiguration(t *testing.T) {
    // Use the in-memory filesystem
    AppFs := afero.NewMemMapFs()
    
    // Pre-populate the memory filesystem for the test
    configPath := "/test/config.json"
    afero.WriteFile(AppFs, configPath, []byte(`{"feature": true}`), 0644)

    // Run the test entirely in memory
    err := ProcessConfiguration(AppFs, configPath)
    if err != nil {
        t.Fatal(err)
    }
}
```

--------------------------------

### Build Virtual File Tree and Adapt to io/fs

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

Creates an in-memory file system, builds a virtual file tree, and then adapts it to the standard io/fs interface for use with library functions. This is useful for testing and creating dynamic file structures.

```go
package main

import (
    "fmt"
    "github.com/spf13/afero"
    "io/fs"
)

func main() {
    // Create in-memory filesystem
    afs := afero.NewMemMapFs()

    // Build virtual file tree
    afs.MkdirAll("src/main", 0o755)
    afero.WriteFile(afs, "src/main/app.go", []byte("package main"), 0o644)
    afero.WriteFile(afs, "go.mod", []byte("module example"), 0o644)
    afero.WriteFile(afs, "README.md", []byte("# Example"), 0o644)

    // Adapt to io/fs
    iofs := afero.NewIOFS(afs)

    // List all files
    fs.WalkDir(iofs, ".", func(path string, d fs.DirEntry, err error) error {
        if !d.IsDir() {
            content, _ := iofs.ReadFile(path)
            fmt.Printf("%s (%d bytes)\n", path, len(content))
        }
        return nil
    })

    // Get subdirectory view
    srcFS, _ := iofs.Sub("src")
    entries, _ := srcFS.ReadDir(".")
    for _, e := range entries {
        fmt.Println("In src:", e.Name())
    }
}
```

--------------------------------

### Build Cloud-Agnostic Applications with Afero

Source: https://github.com/spf13/afero/blob/master/README.md

This pattern allows applications to work seamlessly with different storage backends like local disk, cloud storage, or memory by abstracting filesystem operations.

```go
type DocumentProcessor struct {
    fs afero.Fs
}

func NewDocumentProcessor(fs afero.Fs) *DocumentProcessor {
    return &DocumentProcessor{fs: fs}
}

func (p *DocumentProcessor) Process(inputPath, outputPath string) error {
    // This code works whether fs is local disk, cloud storage, or memory
    content, err := afero.ReadFile(p.fs, inputPath)
    if err != nil {
        return err
    }
    
    processed := processContent(content)
    return afero.WriteFile(p.fs, outputPath, processed, 0644)
}

// Use with local filesystem
processor := NewDocumentProcessor(afero.NewOsFs())

// Use with Google Cloud Storage
processor := NewDocumentProcessor(gcsFS)

// Use with in-memory filesystem for testing
processor := NewDocumentProcessor(afero.NewMemMapFs())
```

--------------------------------

### OsFs Name Method

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/osfs-memfs.md

Returns the string "OsFs", identifying the filesystem implementation.

```go
func (OsFs) Name() string
```

--------------------------------

### Archive Filesystem Constructors

Source: https://github.com/spf13/afero/blob/master/_autodocs/README.md

Create filesystems from zip or tar archives. These allow you to treat archive contents as a filesystem.

```go
// Archives
zipfs.New(r *zip.Reader) afero.Fs
tarfs.New(t *tar.Reader) *tarfs.Fs
```

--------------------------------

### Inject OsFs for Production Usage

Source: https://github.com/spf13/afero/blob/master/README.md

In your production environment, inject the `OsFs` backend to use the real operating system filesystem. This is done by creating an instance of `afero.NewOsFs()` and passing it to your refactored functions.

```go
func main() {
    // Use the real OS filesystem
    AppFs := afero.NewOsFs()
    ProcessConfiguration(AppFs, "/etc/myapp.conf")
}
```

--------------------------------

### Sub Directory Access with IOFS

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

Shows how to create a subdirectory view using `iofs.Sub`, which allows treating a subdirectory as a separate filesystem.

```go
iofs := afero.NewIOFS(afs)

// Create subdirectory filesystem
subfs, err := iofs.Sub("config")
if err != nil {
    // Subdirectory doesn't exist
}

// Now "config/file.txt" becomes "file.txt"
content, _ := subfs.ReadFile("file.txt")
```

--------------------------------

### Core Filesystem Constructors

Source: https://github.com/spf13/afero/blob/master/_autodocs/README.md

Use these to create fundamental filesystem instances. NewOsFs() uses the actual operating system's filesystem, while NewMemMapFs() creates an in-memory filesystem.

```go
// Core
afero.NewOsFs() Fs
afero.NewMemMapFs() Fs
```

--------------------------------

### Testing Pattern with In-Memory Filesystem in Go

Source: https://github.com/spf13/afero/blob/master/_autodocs/patterns-and-architecture.md

Utilize afero.NewMemMapFs() for testing to create an in-memory filesystem. This allows for isolated and fast testing of file operations without touching the actual disk.

```go
func ProcessConfig(fs afero.Fs, configPath string) error {
    content, err := afero.ReadFile(fs, configPath)
    if err != nil {
        return err
    }
    // Process content...
    return nil
}

func TestProcessConfig(t *testing.T) {
    // Use in-memory filesystem for tests
    fs := afero.NewMemMapFs()
    afero.WriteFile(fs, "/config.json", []byte(`{"key":"value"}`), 0o644)
    
    if err := ProcessConfig(fs, "/config.json"); err != nil {
        t.Fatal(err)
    }
}

func main() {
    // Use OS filesystem in production
    fs := afero.NewOsFs()
    ProcessConfig(fs, "config.json")
}
```

--------------------------------

### Testing ProcessConfig with MemMapFs

Source: https://github.com/spf13/afero/blob/master/_autodocs/INDEX.md

Demonstrates how to test a function that depends on the Fs interface using an in-memory filesystem. Ensure the necessary files are created before calling the function under test.

```go
func ProcessConfig(fs afero.Fs, path string) error { ... }
```

```go
func TestProcessConfig(t *testing.T) {
    fs := afero.NewMemMapFs()
    afero.WriteFile(fs, "/config.json", []byte(`{}`), 0o644)
    ProcessConfig(fs, "/config.json")
}
```

--------------------------------

### html/template.ParseFS Integration

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

Demonstrates loading HTML templates from an Afero filesystem using the IOFS adapter with html/template.ParseFS.

```go
import (
    "github.com/spf13/afero"
    "html/template"
)

func main() {
    afs := afero.NewMemMapFs()
    afero.WriteFile(afs, "tmpl.html", []byte("{{.Name}}"), 0o644)

    iofs := afero.NewIOFS(afs)
    t, err := template.ParseFS(iofs, "tmpl.html")
    if err != nil {
        // handle error
    }

    // Use template t
}
```

--------------------------------

### Create RegexpFs

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/composite-filesystems.md

Creates a filesystem filtered by a regular expression. The source filesystem and the regex are required parameters.

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

--------------------------------

### Detecting File System Errors in Go

Source: https://github.com/spf13/afero/blob/master/_autodocs/INDEX.md

Demonstrates how to check for common file system errors like 'not exists', 'exists', 'permission denied', and specific Afero errors. Use standard library functions and errors.Is for robust error handling.

```go
if os.IsNotExist(err) { /* file not found */ }
if os.IsExist(err) { /* file exists */ }
if os.IsPermission(err) { /* permission denied */ }
if errors.Is(err, afero.ErrNoSymlink) { /* no symlink support */ }
```

--------------------------------

### Create BasePathFs Filesystem

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/composite-filesystems.md

Creates a filesystem that restricts all operations to a specified subdirectory. Use this to sandbox operations or implement chroot-like behavior.

```go
func NewBasePathFs(source Fs, path string) Fs
```

--------------------------------

### OsFs Methods

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/osfs-memfs.md

OsFs provides methods that directly correspond to and delegate to functions in the standard Go `os` package. These methods cover common file operations such as creating, opening, removing, and renaming files and directories.

```APIDOC
## OsFs Methods

### Description
All methods delegate to the corresponding `os` package functions. For detailed behavior, see the `os` package documentation.

### Methods Overview

| Method | Underlying Function | Description |
|---|---|---|
| Create | `os.Create` | Creates a file with mode 0o666. |
| Open | `os.Open` | Opens file read-only. |
| OpenFile | `os.OpenFile` | Opens file with flags and permissions. |
| Remove | `os.Remove` | Removes a file or empty directory. |
| RemoveAll | `os.RemoveAll` | Recursively removes a file or directory. |
| Mkdir | `os.Mkdir` | Creates a directory. |
| MkdirAll | `os.MkdirAll` | Creates directory and parents. |
| Rename | `os.Rename` | Renames or moves a file. |
| Stat | `os.Stat` | Gets file information. |
| Chmod | `os.Chmod` | Changes file permissions. |
| Chown | `os.Chown` | Changes file owner/group (Unix-like only). |
| Chtimes | `os.Chtimes` | Changes file access/modification times. |
| LstatIfPossible | `os.Lstat` | Gets file info without following symlinks. Returns (info, true, error). |
| SymlinkIfPossible | `os.Symlink` | Creates a symlink (Unix-like only). |
| ReadlinkIfPossible | `os.Readlink` | Reads symlink target (Unix-like only). |
```

--------------------------------

### Create Temporary Directory - Go

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/utility-functions.md

Creates a temporary directory with a specified prefix. The caller must remove the directory when done. Retries up to 10,000 times if the directory already exists. The prefix cannot contain path separators.

```go
func TempDir(fs Fs, dir, prefix string) (name string, error)
func (a Afero) TempDir(dir, prefix string) (name string, error)
```

```go
tmpDir, err := afero.TempDir(fs, "/tmp", "build_")
if err != nil {
    return err
}
defer fs.RemoveAll(tmpDir)

// Use tmpDir for temporary files
```

--------------------------------

### Create IOFS Adapter

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

Creates an adapter that implements the io/fs.FS interface for any Afero filesystem.

```go
func NewIOFS(fs Fs) IOFS
```

--------------------------------

### Checking for Specific Errors (os.IsNotExist, os.IsExist)

Source: https://github.com/spf13/afero/blob/master/_autodocs/errors.md

Illustrates how to check if an error is a specific known error type like 'not exist' or 'already exist'.

```go
// Good
if os.IsNotExist(err) {
    // File not found
} else if os.IsExist(err) {
    // File exists
}
```

--------------------------------

### Import Paths for Afero

Source: https://github.com/spf13/afero/blob/master/_autodocs/INDEX.md

Import the core Afero library and specific filesystem implementations like zipfs and tarfs.

```go
import "github.com/spf13/afero"
import "github.com/spf13/afero/zipfs"
import "github.com/spf13/afero/tarfs"
```

--------------------------------

### IOFS Path Restrictions and Workarounds

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/io-fs-integration.md

Demonstrates how IOFS handles absolute paths and parent directory traversal. Use relative paths or the Sub() method to overcome these limitations.

```go
// Cannot: Use absolute path
iofs.Open("/absolute/path")  // Invalid

// Solution: Use relative path
iofs.Open("path/to/file")

// Cannot: Traverse up with ..
iofs.Open("config/../data")  // Invalid

// Solution: Use flat structure or Sub()
dataFS, _ := iofs.Sub("data")
dataFS.ReadFile("file.txt")
```

--------------------------------

### Serve Afero Filesystem with net/http in Go

Source: https://github.com/spf13/afero/blob/master/_autodocs/README.md

Serve files from an Afero filesystem over HTTP using either the HttpFs wrapper or the IOFS adapter. This allows you to expose your virtual filesystem via a web server.

```go
// Serve Afero filesystem over HTTP
afs := afero.NewMemMapFs()
afero.WriteFile(afs, "index.html", []byte("<h1>Hello</h1>"), 0o644)

// Method 1: HttpFs wrapper
hfs := afero.NewHttpFs(afs)
http.Handle("/", http.FileServer(hfs.Dir("/")))

// Method 2: IOFS adapter
iofs := afero.NewIOFS(afs)
http.Handle("/", http.FileServer(iofs))

http.ListenAndServe(":8080", nil)
```

--------------------------------

### Create Sandboxed Filesystem with Copy-on-Write

Source: https://github.com/spf13/afero/blob/master/README.md

Use CopyOnWriteFs to isolate writes to an in-memory overlay, leaving the base filesystem untouched. Ideal for integration tests or untrusted code execution.

```go
// 1. The base layer is the real OS, made read-only for safety.
baseFs := afero.NewReadOnlyFs(afero.NewOsFs())

// 2. The overlay layer is a temporary in-memory filesystem for changes.
overlayFs := afero.NewMemMapFs()

// 3. Combine them. Reads fall through to the base; writes only hit the overlay.
sandboxFs := afero.NewCopyOnWriteFs(baseFs, overlayFs)

// The application can now "modify" /etc/hosts, but the changes are isolated in memory.
afero.WriteFile(sandboxFs, "/etc/hosts", []byte("127.0.0.1 sandboxed-app"), 0644)

// The real /etc/hosts on disk is untouched.

```

--------------------------------

### Create CopyOnWriteFs

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/composite-filesystems.md

Creates a filesystem that copies files on write. It takes a read-only base filesystem and a writable overlay filesystem.

```go
func NewCopyOnWriteFs(base Fs, layer Fs) Fs
```

--------------------------------

### Name Method

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/osfs-memfs.md

Returns the name of the filesystem implementation.

```APIDOC
## Name()

### Description
Returns the identifier for this filesystem implementation.

### Method Signature
```go
func (m *MemMapFs) Name() string
```

### Return Value
- **string**: Returns the string "MemMapFS".
```

--------------------------------

### NewHttpFs Constructor

Source: https://github.com/spf13/afero/blob/master/_autodocs/api-reference/archive-filesystems.md

Wraps an existing Afero filesystem to make it compatible with http.FileServer. The source parameter accepts any Afero Fs implementation.

```go
func NewHttpFs(source Fs) *HttpFs
```
Tokens:
Raw