Git Reference ยท Maintenance and Recovery
git fast-export command
Reference for git fast-export: print commits as a fast-import stream, copy or filter repositories, anonymize history, and use marks for incremental export.
git fast-export writes the history you select as a stream of text commands that git fast-import can read. The stream names every blob once, then lists each commit with its author, committer, message and the file changes it makes. Because the format does not depend on Git's storage layout, it works as a neutral exchange format between Git repositories and other version control systems.
Typical uses: copying a repository selectively, rewriting history with an external script (edit the stream, then import it), migrating to another system, creating a shareable but anonymized version of a history for bug reports, and backing up refs without packfile internals.
git fast-export --all > history.stream git fast-export main | git -C ../copy fast-import
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git fast-export [<options>] <rev-list-args>...
Any argument that git rev-list understands selects the history: --all, branch names, main..feature, --since=..., and path limits after --.
| Option | Description |
|---|---|
--all |
Export every ref. |
--progress=<n> |
Insert a progress line every n objects. |
--signed-tags=<mode> |
What to do with signed tags: abort (default), verbatim, warn, warn-verbatim, warn-strip, strip. |
--signed-commits=<mode> |
The same choices for signed commits (verbatim, warn-verbatim, strip, ...). |
--tag-of-filtered-object=<mode> |
A tag points at a commit your filter removed: abort (default), drop or rewrite to the nearest kept ancestor. |
--export-marks=<file>, --import-marks=<file> |
Save and reuse the object-to-mark table to export only new commits next time. --import-marks-if-exists tolerates a missing file. |
--mark-tags |
Give tags marks too, so tools can refer to them. |
--reference-excluded-parents |
Refer to parents outside the exported range by object ID instead of leaving the link out. |
--show-original-ids |
Add original-oid <id> lines naming the source object. |
--no-data |
Skip blob contents; blobs are named by object ID. Useful with --full-tree for structure-only tools. |
--full-tree |
Emit deleteall plus the whole tree for each commit instead of differences. |
--use-done-feature |
End the stream with done, so fast-import --done can detect truncation. |
-M[<n>], -C[<n>] |
Detect renames or copies and emit R and C commands. |
--anonymize |
Replace names, messages, paths and contents with generated tokens; the shape of history is kept. |
--anonymize-map=<from>[:<to>] |
Keep or substitute chosen tokens, such as a branch name, while anonymizing the rest. |
--reencode=<mode> |
yes, no or abort: convert commit messages with other encodings to UTF-8. |
--refspec=<spec> |
Apply a refspec to exported ref names. |
Returns: the stream on standard output; exit status 0 on success. It stops with an error for objects it cannot represent, such as a signed tag in abort mode.
Usage notes
- IDs survive a plain round trip. Exporting everything and importing it into an empty repository recreates identical commit IDs, as the second example shows. Any change to the stream (an edited author, a removed file) changes the IDs of that commit and its descendants.
- Rewriting by filtering the stream. The old technique for large rewrites is to export, edit the text with a script, and import again. Tools such as
git filter-repoare built on this. See Removing secrets from history. - Incremental export. Give
--export-marks=<file>to bothfast-exportandfast-importon the first run, and--import-marks=<file>to both on later runs; objects already in the marks file are not written again. - Path limiting.
git fast-export main -- src/exports only the commits touchingsrc/and only those files. Parents are rewritten, so the new history has different IDs. - Merges appear as
merge :<mark>lines. A merge with a missing parent after filtering becomes a normal commit. - Size. The stream holds every blob in full, uncompressed, so it can be much bigger than the repository. Compress it (
| gzip) if you store it. - Submodules are exported as
160000gitlink entries, never as their contents.