git-archive

Create a tar archive from the contents of the current HEAD and print it to stdout

$ git archive [[-v|--verbose]] HEAD

$ git archive [[-v|--verbose]] --format zip HEAD

$ git archive [[-v|--verbose]] [[-o|--output]] [path/to/file.zip] HEAD

$ git archive [[-o|--output]] [path/to/file.tar] [branch_name]

$ git archive [[-o|--output]] [path/to/file.tar] HEAD:[path/to/directory]

$ git archive [[-o|--output]] [path/to/file.tar] --prefix [path/to/prepend]/ HEAD

git archive [--format=<fmt>] [--output=<file>] [--prefix=<prefix>/] <tree-ish> [<path>...]
git archive --remote=<repo> [options] <tree-ish> [<path>...]

<tree-ish>
    The commit, tag, or branch from which to create the archive. For example, HEAD, main, or a specific commit SHA.

[<path>...]
    Optional pathspecs to limit the archive to specific files or directories within the <tree-ish>.

--format=<fmt>
    Specifies the archive format. Common formats include tar, zip, and tar.gz (or tgz). Use --list to see all supported formats.

--output=<file>
    Writes the archive to the specified <file> instead of standard output. The format can often be inferred from the file extension.

--prefix=<prefix>/
    Prepends <prefix>/ to each file path within the archive, useful for creating clean distribution packages.

--remote=<repo>
    Retrieves the archive from a remote repository instead of the local one, allowing generation without cloning the entire repository.

--list
    Lists the archive formats supported by the current Git build and exits.

git-archive creates a compressed archive (typically tar or zip) of a specified Git tree, such as a branch, tag, or commit ID. It writes the resulting archive to standard output, making it easy to pipe to a file or another command. This command is particularly useful for generating distribution packages or snapshots of a project without including the entire .git directory.

By default, git-archive creates a tar archive, but users can explicitly choose between tar, zip, or tar.gz (among others, depending on configuration) using the --format option. If an output filename is provided via --output, the format can often be inferred from the extension.

When archiving the HEAD commit without specific pathspecs, git-archive intelligently excludes common build artifacts, editor backups, and temporary files, resulting in a cleaner, user-ready distribution. The --prefix option allows for all files within the archive to be placed under a specified directory, which is beneficial for creating well-structured release archives. It's an efficient way to export a clean snapshot of a repository's contents.

One important caveat is the interaction between HEAD (or current worktree), pathspecs, and file exclusion. When archiving HEAD without explicit pathspecs, git-archive automatically excludes common build artifacts, editor backups, and temporary files. However, if any <path> arguments are provided, this automatic exclusion behavior is disabled, and all files matching the pathspec will be included, regardless of their usual excluded status. Users should be aware of this to avoid unintentionally including unwanted files. Additionally, git-archive specifically excludes the entire .git directory, ensuring that only the project's content is archived.

When archiving the HEAD commit (or a commit pointing to the current worktree) without specifying any <path> arguments, git-archive automatically excludes files that are typically not relevant for distribution, such as build products (e.g., *.o, *.so), editor backup files (e.g., *~, *#), and other temporary files. This intelligent exclusion helps create cleaner distribution packages. This behavior can be influenced by configuration settings (e.g., archive.exclude) and .gitattributes files within the repository.

git-archive has been a core utility in Git since its early days, introduced around version 1.5.0. Its primary purpose has always been to provide a clean, distributable snapshot of a Git repository's contents, without including the entire .git directory. While its fundamental functionality has remained stable, subsequent Git versions have introduced enhancements such as the --remote option, allowing direct archiving from remote repositories, which is particularly useful for CI/CD pipelines and automated releases.

git-bundle(1), git-log(1), git-checkout(1), tar(1), zip(1)