go-erofs

A Go library for reading and creating EROFS filesystem images using the standard fs.FS interface.

Features

• Read EROFS images through Go's fs.FS interface
• Create EROFS images from directories or any fs.FS
• Merge multiple filesystem sources with overlay whiteout support
• Metadata-only mode for container layer indexing (chunk-based references to original data)
• Pure Go, no CGO — uses only the standard library

Status

• Read erofs files created with default mkfs.erofs options
• Read chunk-based erofs files with indexes
• Xattr support including long xattr prefixes
• Extra devices for chunked data
• Create erofs files from any fs.FS
• Directory to erofs packing
• AUFS whiteout to overlayfs conversion
• Merge multiple filesystem layers with whiteout processing
• Read erofs files with compression

Reading an EROFS image

f, err := os.Open("image.erofs")
if err != nil {
    log.Fatal(err)
}
defer f.Close()

img, err := erofs.Open(f)
if err != nil {
    log.Fatal(err)
}

fs.WalkDir(img, ".", func(path string, d fs.DirEntry, err error) error {
    fmt.Println(path)
    return nil
})

Merging multiple layers

Combine multiple filesystem sources into one image. The Merge option enables overlay semantics — AUFS-style whiteout files (.wh.<name>) delete entries from prior layers:

outFile, _ := os.Create("merged.erofs")
w := erofs.Create(outFile)

w.CopyFrom(baseLayer)
w.CopyFrom(overlayLayer, erofs.Merge())
w.Close()

Merge can also be combined with MetadataOnly to build a merged index without copying data:

w := erofs.Create(outFile)
w.CopyFrom(layer1, erofs.MetadataOnly())
w.CopyFrom(layer2, erofs.MetadataOnly(), erofs.Merge())
w.Close()

Building an image programmatically

outFile, _ := os.Create("image.erofs")
w := erofs.Create(outFile)

f, _ := w.Create("/hello.txt")
f.Write([]byte("hello world\n"))
f.Close()

w.Mkdir("/dir", 0o755)
w.Symlink("hello.txt", "/link")

w.Close()
outFile.Close()