Documentation
¶
Overview ¶
Package archive packs and updates zip/tar archives using the Go standard library only, so archive creation behaves identically on macOS, Linux, and Windows without depending on the `zip`/`tar` binaries. See docs/prd/archive-step.md.
Index ¶
Constants ¶
const ( FormatZip = "zip" FormatTar = "tar" FormatTGZ = "tgz" FormatTarBz2 = "tar.bz2" FormatTarXz = "tar.xz" )
Supported archive formats. Writing tar.bz2 and tar.xz is not yet implemented even though both are recognized formats — the Go standard library has no xz support and only read-only bzip2; see ErrArchiveFormatNotImplemented.
const ( // MtimeFilesystem is the default: every entry carries the source file's // real mtime and permission bits, straight through from os.Stat. MtimeFilesystem = "filesystem" // MtimeEpoch applies one timestamp to every entry: the most recent // commit that touched anything under Source, so output is identical // across checkouts/machines regardless of real file mtimes. Named after // the SOURCE_DATE_EPOCH reproducible-builds convention, which this mode // mirrors conceptually (one shared reference timestamp for the whole // build) even though the value itself comes from git history rather // than an environment variable. MtimeEpoch = "epoch" // MtimeGit resolves each entry's own most recent commit, falling back // to the epoch value (same lookup MtimeEpoch uses) for files git has no // history for — the common case for this step, since it typically // packages build output (node_modules, compiled binaries) rather than // tracked source. MtimeGit = "git" )
Entry mtime modes: the modification-time metadata stamped into each archive entry (not the source files on disk, and not the archive file's own OS-level mtime). Both non-filesystem modes also normalize permission bits (and, for tar, zero the owner/group fields) — that half of the problem is independent of which timestamp strategy is used, and is the actual root cause behind Terraform's archive_file provider still producing non-reproducible output years after it shipped: umask differs across environments, so the same content gets different permission bits baked into the archive on different machines.
Variables ¶
This section is empty.
Functions ¶
func DetectFormat ¶
DetectFormat resolves the archive format to use. An explicit format always wins; otherwise the format is inferred from path's extension.
Types ¶
type Action ¶
type Action string
Action names the archive verb. Only ActionReplace and ActionUpdate are implemented; ActionCreate and ActionExtract are reserved in the schema for a future phase so it never needs a breaking change.
type PackOptions ¶
type PackOptions struct {
// Source is the directory or file to archive.
Source string
// Destination is the archive file to write.
Destination string
// Format is the archive format; empty infers it from Destination's extension.
Format string
// Subpath nests Source's content under this path inside the archive.
Subpath string
// Include, if non-empty, keeps only files matching at least one glob.
Include []string
// Exclude drops files matching any glob, evaluated before Include.
Exclude []string
// Mtime controls the modification-time metadata stamped into each
// archive entry (not the source files on disk, and not the archive
// file's own OS-level mtime): "filesystem" (the default, same as
// omitting the field) preserves each source file's real mtime and mode;
// "epoch" pins every entry to the same timestamp (the most recent git
// commit touching Source); "git" resolves each entry's own most recent
// commit and falls back to the epoch value for files git has no history
// for. "epoch"/"git" also normalize permission bits, since umask
// differences are the actual root cause of non-reproducible archives,
// not just timestamps.
Mtime string
}
PackOptions configures a pack (replace/update) operation.
Source Files