Git Archive

Intermediate

Learner goal

By the end of this lesson, you should be able to create a release archive from a Git tree, commit, or tag; choose an archive format and path scope; add a safe filename prefix; understand how archive attributes affect exported content; and recover the commit ID recorded in a tar archive.

`git archive` exports a named tree

`git archive <tree-ish>` creates an archive containing the tree structure represented by the supplied tree-ish. A commit or tag selects a repository snapshot; a raw tree ID is also accepted. With no explicit path, Git includes the files and subdirectories in the selected tree. One or more path arguments restrict the exported paths.

git archive --format=tar HEAD > source.tar
git archive --format=tar release-2.0 > release-2.0.tar
git archive --format=tar HEAD src/ > src.tar

git archive --format=tar release-2.0 > release.tar?Git exports the selected snapshot

Commit/tag input carries archive metadata

Git treats a tree ID differently from a commit or tag ID for archive metadata. When a commit or tag is archived, the commit time is used for archive entry modification times, and tar output stores the commit ID in a global extended PAX header. `git get-tar-commit-id` can extract that ID. A tree ID does not provide that commit identity.

git archive --format=tar HEAD > build.tar
git get-tar-commit-id < build.tar

git rev-parse HEAD

git get-tar-commit-id < build.tar?the recorded commit ID, when the archive contains one

Choose format and output deliberately

Git supports `tar`, `zip`, `tar.gz`, and `tgz`, plus formats defined through `tar.<format>.command`. With `--output=<file>`, Git can infer a format from the filename when possible; otherwise the default output format is tar. Explicit `--format` is useful when the artifact format is part of a reproducible release procedure.

git archive --format=tar.gz --output=release.tar.gz HEAD
git archive --format=zip --output=release.zip HEAD
git archive --list

git archive --format=tar.gz --output=release.tar.gz HEAD?Git writes a gzip-compressed tar artifact

Prefixes make extracted release trees predictable

`--prefix=<prefix>/` prepends the specified path to tracked files in the archive. This is useful when a release should extract into a versioned top-level directory rather than scattering files into the current directory. The official documentation warns that prefixes are used as supplied and are not normalized, so avoid unsafe path components such as `../` in release procedures.

git archive --format=tar --prefix=project-2.0/ --output=project-2.0.tar release-2.0
tar tf project-2.0.tar | head

git archive --prefix=project-2.0/ HEAD > project.tar?archived paths begin under project-2.0/

Path arguments can export only part of a snapshot

After the tree-ish, path arguments restrict what Git puts into the archive. This is different from selecting a different commit: the archive still comes from the same named tree-ish, but only the requested paths are included.

git archive --format=tar HEAD docs/ LICENSE > docs-and-license.tar

git archive --format=tar HEAD docs/?only the docs/ path is exported

`export-ignore` controls archive membership

The `export-ignore` attribute prevents matching files and directories from being added to archive files. The attribute is normally read from `.gitattributes` in the tree being archived. This lets a repository keep development-only files under version control while excluding them from a release artifact.

printf 'tests/ export-ignore\n' >> .gitattributes
git add .gitattributes && git commit -m 'Exclude tests from exports'
git archive --format=tar HEAD > release.tar
tar tf release.tar | grep '^tests/' || true

git archive --format=tar HEAD?tests/ is absent from the archive when the attribute applies

`export-subst` expands selected placeholders

The `export-subst` attribute enables Git to expand supported `$Format:...$` placeholders when adding a file to an archive. The expansion depends on having a commit ID: a tree input does not provide the commit identity needed for replacement. This is useful for embedding selected commit metadata in an exported file without changing the committed source before every release.

printf "Release $Format:%H$\n" > RELEASE.txt
printf "RELEASE.txt export-subst\n" >> .gitattributes
git add RELEASE.txt .gitattributes && git commit -m "Add export metadata"
git archive --format=tar HEAD > release.tar
tar -xOf release.tar RELEASE.txt

git archive --format=tar HEAD?supported placeholders can be expanded using the archive commit metadata

`.gitattributes` and `--worktree-attributes` have a deliberate boundary

By default, archive attributes come from `.gitattributes` files in the tree being archived. `--worktree-attributes` additionally asks Git to use `.gitattributes` files from the working tree. This is an explicit escape hatch when archive behavior should reflect current working-tree attributes rather than only the committed tree. It should be used knowingly because it can make the artifact depend on uncommitted attribute changes.

git archive --format=tar HEAD > committed-attributes.tar
git archive --format=tar --worktree-attributes HEAD > worktree-attributes.tar

git archive --format=tar --worktree-attributes HEAD?working-tree attributes are considered

A release archive is a snapshot, not a new Git object database

`git archive` produces a portable file artifact containing selected repository content. It does not create a new commit, tag, or repository history. Treat the resulting tar/ZIP file as a release artifact and verify its contents and recorded commit identity when reproducibility or provenance matters.

git rev-parse HEAD
git archive --format=tar --prefix=project/ HEAD > project.tar
git get-tar-commit-id < project.tar
tar tf project.tar | head

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.

Official references

This lesson is based only on the live official Git documentation: `git-archive` for archive creation, formats, prefixes, paths, attributes, and commit metadata; `git-get-tar-commit-id` for recovering the recorded commit ID; and `gitattributes` for `export-ignore` and `export-subst`. The current official `git-archive` page reports no changes from Git 2.55.0 to 2.56.0.