git archive: Usage, Options & Common CI Errors

git archive packages the files of a commit or tree into a tar or zip - no history, no .git.

Archive is the clean way to produce a release tarball from a tag without shipping Git metadata.

What it does

git archive writes the contents of a tree-ish (commit, tag, or tree) to a tar or zip stream, excluding the repository metadata, optionally adding a path prefix.

Common usage

Terminal

git archive --format=tar.gz -o release.tar.gz v1.2.0
git archive --format=zip --prefix=app/ HEAD -o app.zip
git archive HEAD | tar -x -C /tmp/export

Options

Flag	What it does
--format=<tar\|zip\|tar.gz>	Output archive format
-o / --output=<file>	Write to a file instead of stdout
--prefix=<dir>/	Prepend a directory to every path
--remote=<repo>	Archive directly from a remote
<tree-ish>	Commit, tag, or tree to export

Common errors in CI

fatal: Operation not supported by protocol (for --remote) - many hosts disable remote git archive over HTTP/SSH; clone then archive locally instead. fatal: not a valid object name means the ref does not exist in the (possibly shallow) checkout.

Related guides

git tag: Usage, Options & Common CI Errorsgit tag creates and lists tags for releases. Reference for -a, -m, -d, pushing tags, and the "tag already exi… git show: Usage, Options & Common CI Errorsgit show displays a commit, tag, or object with its diff. Reference for --stat, --name-only, blob viewing, an… git describe: Usage, Options & Common CI Errorsgit describe produces a readable name from the nearest tag, ideal for build versions. Reference for --tags, -… git clone: Usage, Options & Common CI Errorsgit clone copies a remote repository into a new local directory. Reference for depth, branch, and submodule f…