Git Archive

Introduction

Git Archive is a powerful utility that enables you to create compressed archives of your Git repository files. It allows you to export a specific tree (commit, branch, or tag) from your repository into a single file archive (ZIP, TAR) without including the .git directory and its metadata. This feature is particularly useful when you need to share your codebase with someone who doesn't need the entire Git history, or when you want to create a clean distribution package of your project.

Unlike simply copying the directory contents, git archive gives you precise control over which version of your files are included and ensures only tracked files are exported.

Basic Usage

The basic syntax for the git archive command is:

bash

git archive [options] <tree-ish> [<path>...]

Where:

• <tree-ish> is the commit, branch, or tag from which to create the archive
• <path>... (optional) specifies which files or directories to include

Example 1: Creating a ZIP archive of the current HEAD

bash

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

Output: No console output is produced, but a project.zip file will be created in your current directory containing all files from the HEAD commit.

Example 2: Creating a tarball of a specific tag

bash

git archive --format=tar -o release-v1.0.tar v1.0

Output: A release-v1.0.tar file will be created containing all files from the v1.0 tag.

Format Options

Git Archive supports several output formats:

1. ZIP Format:

bash

git archive --format=zip -o archive.zip master

2. TAR Format:

bash

git archive --format=tar -o archive.tar master

3. Compressed TAR (gzip):

bash

git archive --format=tar master | gzip > archive.tar.gz

4. Compressed TAR (bzip2):

bash

git archive --format=tar master | bzip2 > archive.tar.bz2

Advanced Features

Including a Specific Prefix

You can add a prefix to all files in the archive using the --prefix option:

bash

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

This will place all files under a project-v1.0/ directory in the archive, which is useful for ensuring files extract into a specific directory.

Creating Archives of Specific Subdirectories

You can create an archive containing only specific parts of your repository:

bash

git archive --format=zip -o src-only.zip HEAD:src

This creates an archive containing only the contents of the src directory.

Listing Archive Contents Without Extraction

To view the contents of an archive created with git archive without extracting it:

bash

git archive HEAD | tar t

Output:

README.md
src/index.js
src/utils.js
package.json
...

Custom Archive Commands with --remote

Git Archive can create archives from remote repositories using the --remote option:

bash

git archive --remote=[email protected]:username/repo.git --format=zip -o remote-master.zip master

This creates a ZIP archive of the remote repository's master branch without cloning the entire repository first.

Practical Applications

Creating Release Distributions

When releasing a software package, you often want to provide a clean snapshot without Git history:

bash

# Create a release archive for version 2.0
git archive --prefix=myapp-2.0/ --format=tar.gz -o myapp-2.0.tar.gz v2.0

Deploying to Production Servers

When deploying code to production, you can use git archive to create a clean distribution package:

bash

# Create deployment package of the latest code
git archive --format=tar.gz HEAD | ssh user@production "tar xz -C /var/www/app"

This command creates an archive and extracts it directly to the production server in one step.

Backing Up Repository Content

While not a substitute for proper Git backups, you can use git archive to backup the content of specific branches:

bash

# Backup the develop branch
git archive --format=zip -o backup-develop-$(date +%Y%m%d).zip develop

Customizing Archives with .gitattributes

You can control how files are archived using the .gitattributes file:

# .gitattributes
# Exclude files from archives
tests/ export-ignore
.github/ export-ignore
.travis.yml export-ignore

# Set line endings in archives
*.txt text eol=crlf
*.sh text eol=lf

This configuration:

1. Excludes test directories and CI configuration from archives
2. Ensures specific line ending formats in exported files

Working with Archive Streams

Instead of directly creating archive files, you can pipe the output of git archive to other commands:

bash

# Send an archive directly to another system
git archive --format=tar HEAD | ssh user@remote "cat > ~/project.tar"

# Extract directly without creating intermediate files
git archive HEAD | tar -x -C /path/to/extract/

Common Errors and Solutions

"fatal: Unknown archive format 'tar.gz'"

Git archive doesn't directly support combined format names. Use piping instead:

bash

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

"fatal: Not a valid object name"

This occurs when the specified branch, tag, or commit doesn't exist:

bash

# Check if the reference exists
git show-ref --verify --quiet refs/tags/v1.0

# If it doesn't, list available references
git tag
git branch

Summary

Git Archive is a versatile tool that allows you to:

1. Create compressed snapshots of your repository at any point in its history
2. Export only tracked files without Git metadata
3. Share your codebase efficiently with collaborators
4. Create clean release distributions
5. Deploy code to servers without Git overhead

By mastering Git Archive, you have another powerful tool in your Git toolkit that helps you manage and distribute your codebase effectively.

Additional Resources

• Git Archive Official Documentation
• Git Attributes Documentation for archive customization

Practice Exercises

1. Create a ZIP archive of your current project including only the source code files.
2. Create a versioned tarball of your project with a proper prefix for distribution.
3. Set up a .gitattributes file to exclude test and documentation files from archives.
4. Create a one-line command to archive and extract your project to a different directory.
5. Create an archive of a specific past commit in your repository's history.