Git Archive: Export Code Snapshot

Summary: Use git archive to export a versioned copy of your codebase.

When working with Git, there are times when you want to share or deploy a snapshot of your repository—without including the entire Git history or metadata. Whether you need to distribute a stable release, send your code to someone, or package it for deployment, Git provides a built-in way to generate clean archives using the git archive command.

In this article, you'll learn what git archive is, why and how to use it, and see practical examples for various scenarios.

What is `git archive`?

git archive is a Git command that creates an archive file (such as a .zip or .tar) from a specific snapshot (commit, tag, or branch) of your repository.

The resulting archive contains:

Tracked files only: No uncommitted changes, ignored files, or the .git directory.
A specific version: Defined by a branch, tag, or commit.
Optionally customized contents: By path or prefix.

Why use `git archive`?

Some common use cases for git archive include:

Distributing releases: Share source code without Git history.
Preparing deployments: Export files for servers where Git isn’t installed.
Creating backups: Save code snapshots at important points.
Code sharing: Hand over a versioned codebase to teammates or clients.

Basic Usage

The basic syntax is:

git archive <commit> | <options>

Where <commit> can be a branch name (like main), a tag (like v1.0), or a commit hash.

Example: Archive the Latest Commit on `main`

To export a tar file of the latest code on main:

git archive --format=tar --output=project.tar main

For a zip file:

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

Archiving Tagged Releases

Tags are commonly used to mark releases. To export the code snapshot marked by a tag:

git archive --format=zip --output=release-v1.0.zip v1.0

This creates a zip archive of all tracked files at the commit referenced by v1.0.

Customizing the Archive

Add a Directory Prefix

You can add a prefix to all files in the archive, so when unpacked, they're placed in a subfolder:

git archive --format=zip --output=project.zip --prefix=project-v1.0/ v1.0

Now, extracting the archive will create a project-v1.0 directory with all contained files.

Export a Subdirectory

To archive only a specific subfolder:

git archive --format=zip --output=docs.zip main:docs/

This captures only the contents of the docs directory from the main branch.

Selecting Files with `pathspecs`

You can archive specific files or patterns:

git archive main README.md src/ > partial.tar

This archives only README.md and the src/ directory from the main branch.

Archiving from a Bare Repository

On a server, you might have a bare repository (no working tree). git archive works perfectly in this scenario.

git --git-dir=/srv/git/myproject.git archive v1.0 > myproject-v1.0.tar

Examples

1. Export Current Working Tree (including unstaged changes)

git archive works only on committed files. To include unstaged or uncommitted changes, first commit or use regular archive tools (like tar), but note this will also include untracked/ignored files.

2. Generating a Deployment Artifact

git archive --format=tar.gz --prefix=app/ -o app.tar.gz HEAD

The --prefix ensures all files land in an app/ directory after extraction.

Limitations

git archive only includes tracked files from the given commit/branch/tag.
Untracked, uncommitted, and ignored files are not archived.
No .git directory or Git metadata is included.
Does not support excluding certain tracked files (unless using pathspecs to include only what you want).

Integration with CI/CD Pipelines

Many CI/CD tools use git archive to package up repositories for deployment, as it’s fast, reliable, and guarantees a clean, reproducible snapshot.

Summary

The git archive command provides a straightforward, flexible way to export clean snapshots of your project. Whether you're distributing source code, preparing releases, or creating deployment artifacts, it's a valuable tool to have in your Git workflow.

Next time you need to export your codebase—leave the .git baggage behind and let git archive do the work!

References:

Happy archiving!