git archive — Creating Release Bundles

git archive creates a compressed archive (tar or zip) of your repository's files without the .git directory. It is the clean way to package a release or share your code as a snapshot.

Why Not Just Zip the Directory?

If you zip your project folder, you include:

The entire .git directory (all history, all objects)
Untracked files, build artifacts, local configs
Files in .gitignore that should not be distributed

git archive exports only the tracked files at a specific point in time — clean, minimal, and reproducible.

Basic Usage

# Create a tar.gz archive of the current HEAD
git archive --format=tar.gz --prefix=project/ HEAD > project.tar.gz

# Create a zip archive
git archive --format=zip --prefix=project/ HEAD > project.zip

The --prefix=project/ flag adds a top-level directory so that extracting the archive creates a project/ folder instead of dumping files into the current directory.

Archiving a Specific Tag or Branch

# Archive a release tag
git archive --format=tar.gz --prefix=myapp-v1.0/ v1.0.0 > myapp-v1.0.tar.gz

# Archive a specific branch
git archive --format=tar.gz --prefix=myapp-dev/ develop > myapp-dev.tar.gz

Exporting Specific Directories

You can archive only part of the repository:

# Archive just the src directory
git archive --format=tar.gz HEAD -- src/ > src-only.tar.gz

# Archive specific files
git archive --format=zip HEAD -- README.md LICENSE docs/ > docs.zip

Using .gitattributes for Export

You can mark files to be excluded from archives using .gitattributes:

# .gitattributes
tests/           export-ignore
.github/         export-ignore
.gitignore       export-ignore
Makefile         export-ignore

Files marked with export-ignore will not appear in git archive output. This is useful for excluding tests, CI configs, and development files from release bundles.

Use Cases

Release artifacts — create tarballs for each version tag in CI/CD
Sharing code — send a snapshot to someone without Git access
Deployment — deploy a clean archive without .git overhead
Compliance — distribute source code without development history

Common Patterns in CI/CD

# In a CI pipeline: create a release archive from a tag
TAG=$(git describe --tags --abbrev=0)
git archive --format=tar.gz --prefix="${TAG}/" "${TAG}" > "${TAG}.tar.gz"

Key Points

git archive exports tracked files without the .git directory
Use --prefix=name/ to wrap files in a top-level directory
Archive any tag, branch, or commit for reproducible snapshots
Use export-ignore in .gitattributes to exclude files from archives