archive

Documentation

Overview

Package archive provides on-disk tar extraction and deterministic archive creation.

Extract materializes entries into a destination directory via os.Root, which confines every file, directory, and symlink operation to that directory — any entry path that would escape destDir is rejected by the runtime. Symlink *targets* (the contents of a symlink, not its own path) are not policed by os.Root; this package additionally rejects any symlink whose target is non-local via filepath.IsLocal.

Only regular files, directories, and symlinks are extracted. Other entry types (hardlinks, devices, FIFOs, etc.) are skipped by default, or cause a failure when WithErrorOnUnsupportedEntry is set — callers that repack the tree must set it so such entries aren't silently dropped.

Archive creation is designed for reproducible builds: file ordering is lexicographic, timestamps are pinned to Unix epoch, and owner/group metadata is zeroed out. This matches the `tar --sort=name --mtime=@0 --owner=0 --group=0` convention used by source modification scripts.

Index

• func CreateDeterministicArchive(archivePath, sourceDir string, comp Compression) (err error)
• func Extract(archivePath, destDir string, comp Compression, opts ...ExtractOption) (err error)
• func ExtractAuto(archivePath, destDir string, opts ...ExtractOption) error
• func IsArchiveName(filename string) bool
• type Compression
  • func DetectCompression(filename string) (Compression, error)
  • func SniffCompressionFromFile(archivePath string, fallback Compression) (comp Compression, err error)
• type ExtractOption
  • func WithErrorOnUnsupportedEntry() ExtractOption

Functions

func CreateDeterministicArchive

func CreateDeterministicArchive(archivePath, sourceDir string, comp Compression) (err error)

CreateDeterministicArchive creates a new tar archive from the contents of sourceDir and writes it to archivePath on the OS filesystem, replacing any existing file.

The output is deterministic:

• File ordering is lexicographic (via filepath.WalkDir).
• Timestamps are pinned to Unix epoch (1970-01-01 00:00:00 UTC).
• Owner/group IDs and names are zeroed out.
• Gzip output uses best compression with no OS or filename metadata.

Symlink targets are recorded verbatim, including absolute or directory-escaping targets. Extract rejects non-local symlink targets (via filepath.IsLocal), so an archive produced here is not guaranteed to be extractable by Extract when the source tree contains such symlinks.

func Extract

func Extract(archivePath, destDir string, comp Compression, opts ...ExtractOption) (err error)

Extract reads a tar archive, decompresses it, and extracts all entries into destDir. Entry paths are confined to destDir via os.Root: any path that would escape destDir is rejected by the runtime. Symlink targets are validated separately by this package — see the package doc for details.

Only regular files, directories, and symlinks are supported. Other entry types are skipped by default, or fail when WithErrorOnUnsupportedEntry is set (required by callers that repack the tree).

func ExtractAuto

func ExtractAuto(archivePath, destDir string, opts ...ExtractOption) error

ExtractAuto is a convenience wrapper that infers the compression from archivePath's extension via DetectCompression and then calls Extract. Most callers should prefer this over the explicit-compression Extract, which exists for cases where the compression cannot be derived from the filename.

func IsArchiveName

func IsArchiveName(filename string) bool

IsArchiveName reports whether filename has a recognized archive extension. It is a convenience predicate over DetectCompression for classifying a path as an archive without needing the specific compression type.

Types

type Compression

type Compression int

Compression identifies the compression format of an archive.

const (
	// CompressionNone indicates an uncompressed .tar archive.
	CompressionNone Compression = iota
	// CompressionGzip indicates gzip compression (.tar.gz or .tgz).
	CompressionGzip
	// CompressionXZ indicates xz compression (.tar.xz or .txz).
	CompressionXZ
	// CompressionZstd indicates zstandard compression (.tar.zst or .tzst).
	CompressionZstd
)

func DetectCompression

func DetectCompression(filename string) (Compression, error)

DetectCompression determines the compression type from the archive filename.

func SniffCompressionFromFile

func SniffCompressionFromFile(archivePath string, fallback Compression) (comp Compression, err error)

SniffCompressionFromFile determines an existing archive's compression by inspecting its leading magic bytes — authoritative over the filename extension.

type ExtractOption

type ExtractOption func(*extractConfig)

ExtractOption configures the behavior of Extract and ExtractAuto.

func WithErrorOnUnsupportedEntry

func WithErrorOnUnsupportedEntry() ExtractOption

WithErrorOnUnsupportedEntry makes Extract fail on tar entries it cannot materialize (anything but a regular file, directory, or symlink). Without it such entries are skipped; callers that repack the tree should set it so the entries aren't silently dropped from the rebuilt archive.