git fast-import
This command is useful when you need to load a lot of commits, branches, and tags into a repository efficiently, typically when migrating from another version control system or replaying history generated by a script.
This command reads a custom, line-based input format from stdin (usually produced by another tool) and turns it into Git objects (commits, trees, blobs, and tags) directly, bypassing normal porcelain commands for speed. It doesn’t take many mandatory flags by itself; instead, it relies on structured input that describes operations like creating commits, setting file contents, or updating branch heads. Common options include --date-format=<format> to specify how commit dates are provided in the stream (for example, --date-format=raw or --date-format=rfc2822), --force to overwrite existing branches and tags described by the imported stream, and --quiet to reduce progress output. The input format includes commands such as blob, commit, tag, and reset that describe the repository state to be created, and this is what allows it to reconstruct entire histories.
Because this command writes objects directly, it’s typically used as a backend for other tools or scripts, not run by hand during daily development. It can create or update multiple branches in one pass, handle large repositories without checking out files, and be combined with features like marks files to allow incremental imports across multiple runs. You’ll usually see it used in migration pipelines where another tool converts an external history (like Subversion or Mercurial) into the fast-import stream format and pipes it into this command.
A closely related companion is git fast-export, which does the reverse: it generates a fast-import–compatible stream from an existing repository, which you can then feed into this command to clone or filter history efficiently (git fast-export --all | git fast-import). Other commands that address similar goals at a higher level include git filter-repo or the older git filter-branch for rewriting history, as well as git bundle for packaging and transferring repository data; however, those operate on Git-native formats rather than the low-level stream consumed by this command.