git fast-export

Half of repo-to-repo migration. Pairs with fast-import.

🎯 What & why

git fast-export serializes commits, trees, blobs, refs, and tags into a plain-text stream that git fast-import (or any compatible tool) can replay. It is how you move history between repos, anonymize a repo for a bug report, or feed Git data into another VCS.

🧠 Mental model

Reads from the object database and refs; writes a stream to stdout. Nothing is mutated. The stream is a deterministic, line-oriented format documented in git-fast-import(1); marks files let you resume or chain exports.

🛠️ Synopsis

git fast-export [<options>] | git fast-import
git fast-export --all [--signed-tags=<mode>] [--tag-of-filtered-object=<mode>]
                [-M] [-C] [--reencode=(yes|no|abort)] [--refspec=<refspec>]
                [--export-marks=<file>] [--import-marks=<file>]
                [--mark-tags] [--fake-missing-tagger] [--use-done-feature]
                [--no-data] [--full-tree] [--anonymize] [--reference-excluded-parents]
                [--show-original-ids] [--] [<git-rev-list-args>...]

🎚️ Switches & options

Flag	What it does
`--all`	Export every ref. The usual choice when cloning an entire repo into a stream.
`--export-marks=<file>`	Write a mark->sha map. Required if you want to do incremental exports later.
`--import-marks=<file>`	Read a previous mark map so subsequent runs only emit new objects.
`--no-data`	Omit blob contents. Useful when paired with a separate transfer of blobs, or for shape-only debugging.
`--anonymize`	Replace paths, identities, and commit messages with consistent gibberish. The right way to ship a repro to a maintainer.
`--reencode=(yes\|no\|abort)`	Control encoding conversion for `encoding` headers. Default is `abort` on conflict in modern Git.
`--signed-tags=<mode>`	What to do with PGP-signed tags: `verbatim`, `warn`, `warn-strip`, `strip`, or `abort`. Signatures generally do not survive a round-trip.

💡 Use cases

Rehome a repo across hosting providers, history intact, without any network protocol.
Send a maintainer a reproducible bug repro on private code via --anonymize.
Bridge to or from another VCS by writing a translator that consumes the stream.
Build incremental mirroring with --export-marks / --import-marks.

🧪 Examples

Full pipe to a fresh repo

$ git -C src fast-export --all \
  | git -C dst fast-import

Anonymize for a bug report

$ git fast-export --all --anonymize \
  --anonymize-map=secret-stuff:placeholder \
  > anon.stream

Incremental export with marks

# first run
$ git fast-export --all --export-marks=marks.out > full.stream
# next day
$ git fast-export --all --import-marks=marks.out --export-marks=marks.out \
  > delta.stream

Subset of history

$ git fast-export --signed-tags=strip main~100..main > recent.stream

🎓 Recommendations

Use --all plus a marks file. Anything else and you will lose tags or skip refs you cared about.
When sharing a repro, always --anonymize. Assume your filenames are also confidential.
Pipe directly to fast-import when copying locally. Disk-staging the stream is just slower and consumes space.

🪤 Common pitfalls

Signed tags don't round-trip cleanly. Pick a --signed-tags mode consciously or the import side will choke.
Without --export-marks, every run re-streams the entire history. Mirrors get expensive fast.
--no-data produces a stream that fast-import cannot reconstruct objects from on its own; you need the source repo's object database alongside.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.