Git archive guide

Git Archive Examples for ZIP, TAR, Folders, and Releases

The git archive command exports the tracked files from a commit, branch, or tag into a distributable archive. It is useful for release packages, source snapshots, and clean deployments, but it does not include the repository's .git directory or preserve the full commit history needed for a backup.

01 — What it exports

What git archive actually exports

Git builds the archive from a committed tree object rather than copying the current working directory. The result contains files Git knows about at the selected revision, arranged according to that revision's directory structure. Untracked files, ignored build artifacts, and most uncommitted changes are not included.

This behavior makes the output reproducible. Two people archiving the same commit with the same options should receive the same project content, even if their local working directories contain different temporary files. It also means that a file must be committed before it can appear in a normal archive of HEAD.

02 — ZIP archive

Create a ZIP archive from the current commit

The most common example creates a ZIP file from the commit currently checked out. Run the command from inside the repository and choose an output path outside any directory that another build step might clean.

git archive --format=zip --output=project.zip HEAD

HEAD identifies the current commit, not every uncommitted edit visible in the working tree. Open the resulting ZIP and verify representative files before publishing it as a release artifact. If the package needs generated assets, build them first and commit them or add them through a separate packaging step.

03 — TAR archive

Create a compressed TAR archive

Linux release workflows often use a .tar.gz file instead of ZIP. Git can create a compressed TAR archive when the corresponding archive format is available in the installed Git environment.

git archive --format=tar.gz --output=project.tar.gz HEAD

Another portable pattern is to generate a TAR stream and pipe it through gzip. The pipeline makes the compression step explicit and allows additional gzip options when a release process needs them.

git archive --format=tar HEAD | gzip > project.tar.gz

04 — Prefix

Add a top-level directory with --prefix

Without a prefix, project files appear at the root of the archive. A top-level directory keeps extraction tidy and prevents files from spilling into the user's current directory. The prefix must normally end with a slash to behave like a directory name.

git archive --format=zip \
  --prefix=my-project-1.4.0/ \
  --output=my-project-1.4.0.zip \
  v1.4.0

Using a versioned prefix is especially helpful for public releases. It makes the extracted directory identify the project and release without depending on the archive filename. Keep the tag, output name, and prefix consistent to reduce packaging mistakes.

05 — Revisions

Archive a branch, tag, or specific commit

The final argument to git archive can be any revision Git can resolve to a tree. Use a branch name for its latest committed state, a release tag for a stable package, or a commit hash when reproducibility requires an exact revision.

git archive --format=zip --output=main.zip main
git archive --format=zip --output=v2.0.0.zip v2.0.0
git archive --format=zip --output=snapshot.zip 4f2a91c

Release tags are usually easier for humans to review than abbreviated hashes, while commit hashes are unambiguous in automated systems. If tags can be moved in your workflow, record and verify the resolved commit before publishing the archive. Signed or protected release tags can add confidence to the process.

06 — Single folder

Archive only one folder

Add a path after the revision to restrict the archive to a directory or file. This is useful when a monorepo contains several independently distributed components or when documentation is published separately from application code.

git archive --format=zip --output=docs.zip HEAD docs/
git archive --format=tar.gz --output=frontend.tar.gz main apps/frontend/

The selected path is retained inside the archive unless other transformations are applied. Inspect the result to confirm that consumers will receive the desired directory layout. For a package that needs files from several unrelated paths, list each path after the revision or use a dedicated build script.

07 — Export-ignore

Exclude files with export-ignore

Git attributes can exclude development-only files from every future archive. Add the export-ignore attribute to patterns in .gitattributes, commit the change, and build the archive from a revision containing that file.

.github/        export-ignore
tests/          export-ignore
.editorconfig   export-ignore
CONTRIBUTING.md export-ignore

Exclusions should be deliberate rather than based only on reducing file size. Tests, licenses, security documentation, migrations, or build configuration may be required by downstream users even if they are not part of runtime execution. Review the extracted package as a consumer would see it.

08 — Export-subst

Substitute commit information with export-subst

The export-subst attribute allows selected placeholders in a tracked file to be expanded when Git creates the archive. A project can use this to place revision information into a version file without modifying the committed working tree.

VERSION.txt export-subst

Inside the selected file, supported pretty-format placeholders can be placed in an archive substitution marker. Test the exact output with the Git version used by the release environment because substitution rules are more specialized than ordinary shell variable replacement. Do not rely on this mechanism for secrets or environment-specific configuration.

09 — Verify contents

List archive contents without extracting everything

Reviewing the file list is a quick validation step before distribution. Standard ZIP and TAR tools can show the archive paths so missing prefixes, accidental exclusions, or unexpected committed files are visible.

unzip -l project.zip
tar -tzf project.tar.gz

Automated release pipelines can also compare the list against expected paths. This does not prove that the application builds or runs, but it catches packaging errors earlier. For higher assurance, extract into a temporary directory and perform the build or smoke test from the archive itself.

10 — Remote archive

Archive from a remote repository

Git supports --remote when the server allows the git-upload-archive service. This can create an archive from a remote revision without first making a normal working clone, but many hosted services restrict or disable the capability.

git archive --remote=ssh://[email protected]/team/project.git \
  --format=zip \
  --output=project.zip \
  main

Do not build a critical workflow around remote archiving until the exact provider and authentication method have been tested. A shallow clone followed by a local archive may be easier to support across providers. For private repositories, credentials must still be supplied through an approved secure mechanism.

11 — Submodules and LFS

Understand submodules and Git LFS

Submodule contents are not automatically embedded as a complete nested repository by a basic git archive operation. The parent tree records a gitlink pointing to a submodule commit, so release packaging normally needs an additional step that initializes and archives each required submodule. Test the final package rather than assuming the parent command collected everything.

Git LFS also needs explicit verification. Depending on the archive path and provider behavior, a release can contain LFS pointer text instead of the large object content consumers expect. Fetch required LFS objects and use a packaging process designed to include them when binary assets are part of the release.

12 — Not a backup

git archive is not a Git backup

An archive created by this command contains exported project files but not the .git object database, refs, reflogs, remote configuration, or complete history. You cannot extract it and continue normal development with the original branches and commits. For repository backup or duplication, use a mirror clone, a Git bundle, or a backup service designed to preserve repository history.

The distinction matters during recovery. A source ZIP may allow an application to be rebuilt, but it cannot restore deleted branches, identify earlier commit relationships, or recreate tags that were not part of the selected tree. Treat git archive as a release and export tool, not as the only copy of an important repository.

FAQ

Frequently asked questions

Does git archive include commit history?

No. It exports tracked files from the selected revision and omits the Git database and full history. Use a mirror clone or Git bundle for repository-level preservation.

Does git archive include uncommitted files?

Normally it does not because the archive is created from a commit, branch, tag, or other tree object. Commit the required files or add them in a separate controlled packaging step.

How do I archive only one directory?

Place the directory path after the revision, such as git archive --format=zip --output=docs.zip HEAD docs/. Check the extracted path structure before distributing the result.

Why are Git LFS files or submodules missing?

LFS content and submodule repositories have storage behavior outside the parent tree's ordinary file blobs. Fetch and package them explicitly, then test the extracted release artifact.

Use the right Git tool for the job

Choose git archive when you need clean, versioned project files without Git internals. Choose git clone --mirror or git bundle when you need refs and history, and add retained copies when recovery from earlier points in time matters. Automated GitReplica mirrors and archive destinations address repository continuity, while git archive remains ideal for distributable source packages.

Get started free