git fast-import

How most VCS-import tools (svn, hg, bzr) get into Git.

🎯 What & why

git fast-import consumes the stream produced by fast-export (or by hand-rolled importers from Subversion, Mercurial, Bazaar, Perforce, etc.) and builds blobs, trees, commits, tags, and refs directly into the target repo. It is the standard backend for any "import history into Git" tool.

🧠 Mental model

Heavy writer. It writes objects straight into a single packfile under .git/objects/pack/ and updates refs at the end. The working tree and index are untouched; this is a backend tool.

🛠️ Synopsis

git fast-import [--date-format=<fmt>] [--done] [--force] [--max-pack-size=<n>]
                [--big-file-threshold=<n>] [--depth=<n>] [--active-branches=<n>]
                [--export-marks=<file>] [--import-marks=<file>] [--import-marks-if-exists=<file>]
                [--[no-]relative-marks] [--cat-blob-fd=<fd>] [--done] [--quiet] [--stats]
                [--allow-unsafe-features]

🎚️ Switches & options

Flag	What it does
`--date-format=<fmt>`	`raw`, `raw-permissive`, `rfc2822`, or `now`. Set this to match what your importer emits or every commit date will be wrong.
`--max-pack-size=<n>`	Roll over to a new packfile after `n` bytes (e.g. `1g`). Useful for huge imports to keep packs manageable.
`--depth=<n>`	Maximum delta chain depth in the produced pack. Default 50; raise for better compression at the cost of access time.
`--active-branches=<n>`	How many branches fast-import keeps trees in memory for at once. Bump this for imports that touch many refs concurrently.
`--export-marks=<file>`	Write the mark->SHA map after import. Pair with `--import-marks` for resumable / incremental imports.
`--quiet`	Suppress the periodic progress output. Use it in pipelines; do not use it interactively or you will think it hung.
`--stats`	Print packfile and memory statistics at the end. Always read these on a real import; they tell you if `--depth` and `--active-branches` were sane.

💡 Use cases

The receiving end of git fast-export | git fast-import for full repo copies.
The standard target of svn-fast-export, hg-fast-export, bzr-fast-export, and the various P4/CVS bridges.
Bulk-loading synthetic history (test fixtures, benchmark repos, generated commits) without ever touching a working tree.
Resumable migrations: re-run with --import-marks after fixing a streamer bug, without re-creating already-imported commits.

🧪 Examples

Pipe from fast-export

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

Import a Mercurial repo

$ git init hg-mirror && cd hg-mirror
$ hg-fast-export.sh -r /path/to/hg-repo \
  | git fast-import --quiet --stats --export-marks=../hg.marks

Resumable import

$ git fast-import \
  --import-marks-if-exists=marks \
  --export-marks=marks \
  --max-pack-size=2g \
  < stream

Tune for a huge import

$ git fast-import \
  --depth=100 \
  --active-branches=200 \
  --max-pack-size=4g \
  --stats < big.stream

🎓 Recommendations

Always pass --stats on a real import. The packfile size and depth utilization tell you whether you need to repack afterwards.
Use --import-marks / --export-marks from day one. Importers crash; you do not want to start over from commit 1.
After import, run git gc --aggressive once. The pack from fast-import is one shot; a real repack with cross-file deltas usually shrinks it noticeably.

🪤 Common pitfalls

Wrong --date-format silently corrupts every commit date. Match the streamer's format exactly.
Default --active-branches=5 is a memory-saver, not a correctness bound, but a stream that touches more branches than that thrashes hard. Bump it for wide histories.
fast-import does not validate that parent commits exist before they are referenced; a malformed stream can produce a broken repo that only git fsck catches.

🔗 Related modules

📝 Quiz

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