Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Maintenance and Recovery

git fast-import command

Reference for git fast-import: the stream format (blob, commit, tag, reset, marks), options for marks and safety, and how to convert other systems into Git.

git fast-import reads a text stream from standard input and turns it into Git objects and refs, writing a packfile directly instead of creating one loose object per file. It is the engine behind most "convert repository X to Git" scripts: a converter prints a stream describing blobs and commits, pipes it into fast-import, and gets a complete repository back, usually in minutes even for huge histories.

The stream is plain text with a few binary-safe data blocks. You can write it by hand for small jobs, which makes fast-import a handy way to create exact commit histories (for tests, demos or synthetic data) without touching a working tree. Its counterpart is git fast-export.

Terminal
git fast-import [options] < stream

Try it

Bash Build a history from a hand-written 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 Marks, tags and an incremental import

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-import [--force] [--quiet] [--stats] [--allow-unsafe-features]
                [--date-format=<fmt>] [--done] [--max-pack-size=<n>]
                [--depth=<n>] [--active-branches=<n>]
                [--export-marks=<file>] [--import-marks=<file>]
                [--import-marks-if-exists=<file>] [--relative-marks]
                [--export-pack-edges=<file>] [--cat-blob-fd=<fd>] [--big-file-threshold=<n>]

Stream commands:

Command Description
blob Define file content: optional mark :<n>, then data.
commit <ref> Create a commit on the ref: mark, author, committer, data (message), from, merge, then file changes.
M <mode> <dataref> <path> Add or change a file. The dataref is a mark (:5), an object ID or the word inline followed by a data block. Modes: 100644, 100755, 120000 (symlink), 160000 (submodule), 040000 (tree).
D <path> / R <old> <new> / C <src> <dest> Delete, rename or copy a path.
deleteall Remove every file; the following M lines define the whole new tree.
tag <name> Create an annotated tag: from, tagger, data.
reset <ref> Point a ref at a commit (from) or start a fresh branch history.
data <n> or data <<delim> A block of exactly n bytes, or text up to a line holding only the delimiter.
progress, checkpoint, done, get-mark, cat-blob, ls, feature, option Control and query commands.
Option Description
--quiet Do not print the statistics report at the end.
--stats Print the statistics report (the default, unless --quiet is given).
--force Allow updates that are not fast-forwards of an existing ref.
--export-marks=<file> Write the mark-to-ID table at the end, so another run can use it.
--import-marks=<file> Load marks from an earlier run (fails if the file is missing; --import-marks-if-exists does not).
--date-format=<fmt> raw (default, <unix-seconds> <tz>), raw-permissive, rfc2822 or now.
--done Require a final done line; a stream that ends early is rejected, so a crashed exporter cannot leave a partial import.
--allow-unsafe-features Allow feature export-marks= and import-marks= inside the stream, normally refused.
--max-pack-size=<n> Start a new pack when one grows past this size.
--depth=<n> Maximum delta depth in the output pack.

Errors: a malformed stream stops the import with fatal: ... and a line number; objects written so far remain in a temporary pack that is discarded. Because the branch update is applied at the end, a failed run normally changes no ref.

Usage notes

  • The working tree is not touched. Like a push, fast-import only writes objects and refs. After importing into the checked-out branch use git reset --hard (as in the first example) or git checkout.
  • Start on a new branch. A commit to a ref without from makes a new root commit, which fast-import refuses for an existing branch unless you pass --force. To continue an existing branch, name its tip with from refs/heads/<branch>^0.
  • Marks are per-run unless exported. mark :n numbers exist only for the current process. Export and import them to convert a repository in several passes.
  • Dates. The default raw format is Unix seconds plus offset (1767268800 +0000). A missing author line copies the committer.
  • data length. With a byte count the data must be exactly that long; with the delimited form the delimiter must not appear in the data. Delimited data is easier to write by hand, a count is faster for converters.
  • Speed and memory. Objects are written straight to a pack and deltified in a window, which is far faster than git add for 100,000 files. Memory use is bounded by --active-branches and the marks table.
  • Trust. Streams can set arbitrary authors, dates and tree contents. Import untrusted streams into a throwaway repository first.