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:
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
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
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:
- ZIP Format:
git archive --format=zip -o archive.zip master
- TAR Format:
git archive --format=tar -o archive.tar master
- Compressed TAR (gzip):
git archive --format=tar master | gzip > archive.tar.gz
- Compressed TAR (bzip2):
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:
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:
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:
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:
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:
# 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:
# 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:
# 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:
- Excludes test directories and CI configuration from archives
- 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:
# 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:
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:
# 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:
- Create compressed snapshots of your repository at any point in its history
- Export only tracked files without Git metadata
- Share your codebase efficiently with collaborators
- Create clean release distributions
- 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
- Create a ZIP archive of your current project including only the source code files.
- Create a versioned tarball of your project with a proper prefix for distribution.
- Set up a
.gitattributes
file to exclude test and documentation files from archives. - Create a one-line command to archive and extract your project to a different directory.
- Create an archive of a specific past commit in your repository's history.
If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)