pkg/archive

tar/gzip helpers tailored to OCI image layers. Used by the unpack pipeline and by the differ.

Purpose

• Apply a layer tar onto a directory, honoring whiteout files.
• Diff two directory trees into a tar stream.
• Handle Linux device files, hardlinks, and xattrs correctly.
• Cross-platform: Windows tar handling has different rules and lives in sibling files.

Files

• archive.go — high-level Apply(ctx, dst, r), Diff(ctx, oldDir, newDir, opts...), WriteDiff.
• tar.go — the tar reader/writer wrappers with OCI-specific tweaks.
• tar_unix.go / tar_windows.go — platform headers (uid/gid mapping, xattrs).
• compression/ — gzip, zstd, and uncompressed pass-through compressors.
• archivetest/ — golden-image fixtures and helpers used by snapshotters and the differ.

OCI specifics

• Whiteouts: a .wh.<name> file in a layer marks <name> as deleted. Apply translates these into actual filesystem deletes when re-applying onto the parent layer.
• Opaque directories: a .wh..wh..opq file marks the directory as opaque (the parent layer's contents are hidden).
• Symlink/hardlink ordering: tar must extract in a specific order so target files exist when symlinks are created.
• xattrs: preserved if the kernel/filesystem supports them. SELinux labels in particular round-trip through the diff.

Used by

• core/diff/walking/ — the default differ wraps pkg/archive to apply a downloaded layer onto a snapshotter.
• pkg/archive/converter/ — used by the image converter (ctr image convert) to repackage layers.
• pkg/archive/imagetest/ — test fixtures.

Entry points for modification

• New compressor: add to pkg/archive/compression/.
• New whiteout style: extend whiteoutPrefix/whiteoutMetaPrefix handling in archive.go.
• New per-platform header normalization: edit tar_unix.go / tar_windows.go.