Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
git fast-export --all > history.stream
git fast-export main | git -C ../copy fast-import

Try it

Bash Read a stream

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.

Bash Copy a repository through a pipe

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

Terminal
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-repo are built on this. See Removing secrets from history.
  • Incremental export. Give --export-marks=<file> to both fast-export and fast-import on 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 touching src/ 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 160000 gitlink entries, never as their contents.