This error occurs when you specify an archive format that Git doesn't recognize or support. The fix involves using a valid format like tar, zip, or tar.gz, or checking your Git version for format availability.
When you run `git archive` with the `--format` option, Git attempts to create an archive in the specified format. If Git doesn't recognize the format you've specified, it fails with "fatal: Unknown archive format". Git has built-in support for a limited set of archive formats. The core formats are `tar` (the default) and `zip`. Modern versions of Git also support `tar.gz` and `tgz` natively using an internal gzip implementation. Additional formats like `tar.xz` can be configured through Git's `tar.<format>.command` configuration option. This error commonly occurs when users misspell a format name, try to use a format that requires a newer Git version, or attempt to use custom formats that haven't been configured. Older Git versions (before 1.8.0) don't support `tar.gz` natively, which catches many developers off guard when working on older systems.
First, check which archive formats your Git installation supports:
git archive --listThis typically outputs:
tar
tgz
tar.gz
zipIf you don't see the format you need, either your Git version is too old or you need to configure a custom format.
Some formats like tar.gz and tgz were added in newer Git versions:
git --versionFormat support by version:
- tar, zip: All Git versions
- tar.gz, tgz: Git 1.8.0+ (native gzip support)
- Custom formats: Git 1.4.3+ (via configuration)
If you're on an older version, upgrade Git or use a workaround (see step 5).
Make sure you're using the exact format name Git expects:
# Correct format names
git archive --format=tar HEAD > archive.tar
git archive --format=zip HEAD > archive.zip
git archive --format=tar.gz HEAD > archive.tar.gz
git archive --format=tgz HEAD > archive.tgz
# Common mistakes (these will fail):
git archive --format=gzip HEAD # Wrong: 'gzip' is not a format
git archive --format=targz HEAD # Wrong: missing dot
git archive --format=tar.bz2 HEAD # Wrong: not built-in, needs configYou can also let Git infer the format from the output filename:
git archive -o release.zip HEAD # Automatically uses zip format
git archive -o release.tar.gz HEAD # Automatically uses tar.gz formatFor formats like tar.xz or tar.bz2, you need to configure them in Git:
For tar.xz (LZMA compression):
git config --global tar.tar.xz.command "xz -c"For tar.bz2 (bzip2 compression):
git config --global tar.tar.bz2.command "bzip2 -c"Now you can use these formats:
git archive --format=tar.xz HEAD > archive.tar.xz
git archive --format=tar.bz2 HEAD > archive.tar.bz2To verify your configuration:
git config --get-regexp 'tar..*.command'If you can't upgrade Git and need tar.gz output, pipe through gzip manually:
git archive --format=tar HEAD | gzip > archive.tar.gzFor other compression formats:
# bzip2 compression
git archive --format=tar HEAD | bzip2 > archive.tar.bz2
# xz compression
git archive --format=tar HEAD | xz > archive.tar.xz
# zstd compression (if available)
git archive --format=tar HEAD | zstd > archive.tar.zstThis approach works with any Git version that supports the base tar format.
After creating your archive, verify it's valid:
For tar archives:
tar -tzf archive.tar.gz | head -20For zip archives:
unzip -l archive.zip | head -20If you get errors here, the archive may have been corrupted or the format specification was wrong.
### Remote Archive Considerations
When using git archive with remote repositories, the remote server must have the format enabled. For custom formats, set:
git config tar.<format>.remote trueThe tar.gz and tgz formats have remote = true by default in modern Git versions.
Note that some Git hosting services (like Bitbucket Cloud) don't support git archive over HTTPS at all. You may see "Operation not supported by protocol" errors. In these cases:
1. Clone the repository locally first
2. Use SSH instead of HTTPS (if supported)
3. Use the hosting service's API to download archives instead
### Compression Level Options
For zip archives, you can control compression level with the -<digit> option:
git archive -9 --format=zip HEAD > highly-compressed.zip # Best compression
git archive -0 --format=zip HEAD > store-only.zip # No compression (fastest)### CI/CD Pipeline Tips
When using git archive in CI/CD pipelines:
1. Check Git version early in your pipeline to catch format issues
2. Use explicit format flags rather than relying on filename inference
3. Fall back to pipe-through-gzip for maximum compatibility:
if git archive --list | grep -q tar.gz; then
git archive --format=tar.gz HEAD > archive.tar.gz
else
git archive --format=tar HEAD | gzip > archive.tar.gz
fi### Performance Considerations
The built-in tar.gz format uses Git's internal gzip implementation, which may behave slightly differently than system gzip. For reproducible builds, consider:
git archive --format=tar --prefix=myproject/ HEAD | gzip -n > archive.tar.gzThe -n flag to gzip omits the timestamp, making the output deterministic.
warning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server