archives

The archives.FileSystem() function creates a fully-featured fs.FS that provides uniform access to directories, regular files, archives, or compressed archives.

• Opening files: Use fsys.Open(name) to get an fs.File. If the source is compressed, reads are automatically decompressed.
• Listing directories: Use fsys.ReadDir(name) or cast an opened file to fs.ReadDirFile to call ReadDir(0).
• Walking: Use standard fs.WalkDir(fsys, ...) to traverse the structure.

Performance Note for .tar: Tar files are sequential-access. While archives implements optimizations for ReadDir() and fs.WalkDir(), Open() calls may require a full scan of the archive. For high-performance extraction where file system semantics aren't needed, use Tar.Extract() directly.

// filename could be a folder, archive, compressed archive, or regular file
fsys, err := archives.FileSystem(ctx, filename, nil)
if err != nil {
	return err
}

// Open a specific file
f, err := fsys.Open("file")
if err != nil {
	return err
}
defer f.Close()

// List contents of a directory
entries, err := fsys.ReadDir("Playlists")
if err != nil {
	return err
}

// Walk the file system
err := fs.WalkDir(fsys, ".", func(path string, d fs.DirEntry, err error) error {
	return nil
})

You can create archives using FilesFromDisk() to map local files to paths within the archive. To create a compressed archive (like .tar.gz), use the CompressedArchive type, which combines an Archival format (e.g., Tar) and a Compression format (e.g., Gz).

ctx := context.TODO()

// map files on disk to their paths in the archive using default settings (second arg)
files, err := archives.FilesFromDisk(ctx, nil, map[string]string{
	"/path/on/disk/file1.txt": "file1.txt",
	"/path/on/disk/file2.txt": "subfolder/file2.txt",
	"/path/on/disk/file3.txt": "",              // put in root of archive as file3.txt
	"/path/on/disk/file4.txt": "subfolder/",    // put in subfolder as file4.txt
	"/path/on/disk/folder":    "Custom Folder", // contents added recursively
})
if err != nil {
	return err
}

// create the output file we'll write to
out, err := os.Create("example.tar.gz")
if err != nil {
	return err
}
defer out.Close()

// we can use the CompressedArchive type to gzip a tarball
format := archives.CompressedArchive{
	Compression: archives.Gz{},
	Archival:    archives.Tar{},
}

// create the archive
err = format.Archive(ctx, out, files)
if err != nil {
	return err
}

Use archives.Identify() to detect the format of an input stream based on filename and/or file headers.

Note: If your input stream is not an io.Seeker, you must use the returned stream value to ensure you can re-read the bytes consumed during identification. If it is an io.Seeker, the returned stream is the same as the input.

Once identified, you can type-assert the returned format to interfaces like archives.Extractor or archives.Decompressor to perform operations.

// unless your stream is an io.Seeker, use the returned stream value to
// ensure you re-read the bytes consumed during Identify()
format, stream, err := archives.Identify(ctx, "filename.tar.zst", stream)
if err != nil {
	return err
}

// you can now type-assert format to whatever you need

// want to extract something?
if ex, ok := format.(archives.Extractor); ok {
	// ... proceed to extract
}

// or maybe it's compressed and you want to decompress it?
if decomp, ok := format.(archives.Decompressor); ok {
	rc, err := decomp.OpenReader(unknownFile)
	if err != nil {
		return err
	}
	defer rc.Close()

	// read from rc to get decompressed data
}

When an archive is extracted to disk, it may not create a new top-level container folder. This causes a discrepancy where a file path like a/b/c inside an archive becomes b/c on disk (if a was the root of the extraction).

To write code that works uniformly whether you are accessing the archive directly or an extracted directory, use the TopDir* functions. These functions attempt to open/stat/read the path as provided; if that fails, they automatically try the path without its first element (e.g., if a/b/c fails, they try b/c).

Note: These functions are EXPERIMENTAL and subject to change or removal.

import (
	"io/fs"
	"github.com/mholt/archives"
)

// Example usage of TopDirOpen
file, err := archives.TopDirOpen(myFsys, "a/b/c")
if err != nil {
	// handle error
}

// Other available TopDir functions:
// archives.TopDirStat(fsys, name) -> (fs.FileInfo, error)
// archives.TopDirReadDir(fsys, name) -> ([]fs.DirEntry, error)