How to use the `git archive` command

The git archive allows you to create archives of your repository's files. Unlike git commit which takes a snapshot of the current state of the branch, git archive generates a tar or zip file of your repository's contents at a specific point in time and can be generated based on commits, branches, or tags. These archives are particularly useful for deployments, backups, or sharing code atomically, without including the entire history of the repository.

This guide will explore the git archive command in depth, including examples and different use-cases.

Basic usage

Archiving the HEAD commit

To create an archive of the current HEAD commit, the last commit made on the branch currently checked-out you can run:

git archive --format=tar HEAD > project.tar

This command creates a tar archive named project.tar containing the contents of the entire repository (excluding the .git folder), as it exists in the current HEAD commit.

Specifying an archive format

By The git archive command supports several archive formats, including tar and zip.

By default, the command will use the tar format but we can also choose a specific format using the --format option. For example if we wanted to export our repository to a .zip file, we can run:

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

This command generates a zip archive of the HEAD commit, saving the compressed zip file to the current directory.

Advanced examples

Archiving a specific branch or tag

To archive a specific branch, pass in the desired branch name directly:

git archive --format=zip feature-xyz > feature-xys.zip

This for example, will create a zip file of the feature-xyz branch.

Similarly, to archive a tag you can run:

git archive --format=zip v1.0 > v1.0.zip

This creates a compressed zip file containing the repository's contents at the state of the v1.0 tag.

Archiving a specific folder

Instead of archiving the entire repository, you can also choose a specific directory. To archive a directory within your project, use the --output option to specify the archive name and path, and the path parameter to define the directory to archive:

git archive --format=zip --output=src.zip HEAD src/

This command creates a zip archive named src.zip containing only the src directory, in the state of the current HEAD commit.

Archiving a remote Git repository

The --remote flag allows you to create an archive of a repository that's hosted remotely, without needing to have the repo stored on your local machine.

Syntax

git archive --remote=<repository URL> <branch> | <commit> | <tag> | <tree-ish> <path> | <format> | <output>

• --remote=<repository URL>: Specifies the URL of the remote repository.
• <branch>, <commit>, <tag>, <tree-ish>: Specifies the point in the repository's history from which to create the archive. This could be a branch name, a specific commit ID, a tag, or another identifier.
• <path>: (Optional) Specifies a subdirectory to archive, rather than the whole repository.
• <format>: (Optional) Specifies the archive format (e.g., tar or zip). Git will attempt to guess the format based on the output file extension if this is not specified.
• <output>: (Optional) Specifies the output file name. If not specified, the archive will be sent to the standard output.

Suppose you want to create a zip archive of the main branch of a remote repository located at https://example.com/myrepo.git. The following command demonstrates how to do this, outputting the archive to a file named myrepo-main.zip:

git archive --remote=https://example.com/myrepo.git main | gzip > myrepo-main.zip

This command instructs Git to connect to the remote repository at https://example.com/myrepo.git, archive the main branch, compress it using gzip, and then write it to a file named myrepo-main.zip.

Notes

• The ability to use the --remote option with git archive depends on the server-side Git configuration. The remote repository must have the upload-archive service enabled, which is not always the case for security and performance reasons.
• If you encounter issues using --remote, consider cloning the repository and using git archive locally.
• Remember to replace https://example.com/myrepo.git and main with the actual URL of your remote repository and the branch, commit, tag, or tree-ish you wish to archive.

Using git archive with the --remote flag is a convenient way to quickly grab a snapshot of a remote repository's contents without cloning or pulling the repository to your local machine.

For further reading on archiving Git repositories, see the official Git documentation.