# Afero — Uniform Filesystem Abstraction for Go

> Afero provides a uniform interface for filesystem operations in Go, allowing code to work transparently with OS filesystems, in-memory filesystems, or cloud storage backends. It is widely used for testing, configuration, and portable file handling.

## Install

Save in your project root:

# Afero — Uniform Filesystem Abstraction for Go

## Quick Use
```bash
go get github.com/spf13/afero
```
```go
fs := afero.NewMemMapFs()
afero.WriteFile(fs, "/tmp/test.txt", []byte("hello"), 0644)
data, _ := afero.ReadFile(fs, "/tmp/test.txt")
```

## Introduction
Afero is a filesystem abstraction library for Go created by Steve Francia (spf13). It defines an `Fs` interface that mirrors the `os` package, letting applications swap between real filesystems, in-memory filesystems, and custom backends without changing business logic. This makes code testable, portable, and easier to reason about.

## What Afero Does
- Provides a drop-in `Fs` interface compatible with standard `os` file operations
- Includes an in-memory filesystem (MemMapFs) for fast, isolated testing
- Offers a read-only filesystem wrapper to enforce immutability
- Supports layered union filesystems that overlay multiple backends
- Ships utility functions (ReadFile, WriteFile, Walk, Exists) that mirror the os and io/ioutil packages

## Architecture Overview
Afero defines the `Fs` interface with methods matching `os.Create`, `os.Open`, `os.Stat`, and related operations. Concrete implementations include `OsFs` (delegates to the real OS), `MemMapFs` (stores files in a thread-safe map), `BasePathFs` (restricts access to a subtree), and `ReadOnlyFs` (wraps any Fs and rejects writes). Union filesystems compose multiple layers with configurable read and write priorities.

## Self-Hosting & Configuration
- Add to your project with `go get github.com/spf13/afero`
- Use `afero.NewOsFs()` for production and `afero.NewMemMapFs()` for tests
- Restrict file access to a directory with `afero.NewBasePathFs(base, "/app/data")`
- Combine layers with `afero.NewCopyOnWriteFs(readOnly, writable)` for overlay patterns
- All implementations are safe for concurrent use

## Key Features
- Drop-in replacement for os file operations via a single interface
- MemMapFs enables deterministic, fast tests without touching disk
- BasePathFs sandboxes file access to a specific directory subtree
- CopyOnWriteFs supports union mounts for layered file systems
- Used by Hugo, Viper, Cobra, and other widely adopted Go projects

## Comparison with Similar Tools
- **os package** — Afero wraps os with an interface, adding testability and portability
- **embed.FS** — read-only embedded files; Afero supports full read-write operations
- **Billy (go-git)** — similar abstraction but tightly coupled to go-git; Afero is general-purpose
- **io/fs (Go 1.16)** — read-only interface; Afero provides read-write plus layered composition
- **testify mock** — mocks individual calls; Afero gives a complete in-memory filesystem

## FAQ
**Q: Is MemMapFs thread-safe?**
A: Yes, MemMapFs uses internal locks and is safe for concurrent reads and writes.

**Q: Can I use Afero with cloud storage like S3?**
A: Afero defines the interface; community packages like afero-s3 implement the Fs interface for cloud backends.

**Q: How does Afero relate to Viper and Cobra?**
A: All three are by spf13. Viper uses Afero for configuration file access, and Cobra uses Viper for config. Afero is the filesystem layer in this stack.

**Q: Does Afero support file watchers?**
A: Afero does not include built-in file watching. Use fsnotify alongside OsFs for change notifications.

## Sources
- https://github.com/spf13/afero
- https://pkg.go.dev/github.com/spf13/afero

---
Source: https://tokrepo.com/en/workflows/asset-f5071ce9
Author: AI Open Source