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
- type ExtractOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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 ¶
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.
Source Files