This program is usually not what the end user wants to run directly.
Most end users want to use one of the existing frontend programs,
which parses a specific type of foreign source and feeds the contents
-stored there to 'git-fast-import'.
+stored there to 'git fast-import'.
fast-import reads a mixed command/data stream from standard input and
writes one or more packfiles directly into the current repository.
with the newly imported data.
The fast-import backend itself can import into an empty repository (one that
-has already been initialized by 'git-init') or incrementally
+has already been initialized by 'git init') or incrementally
update an existing populated repository. Whether or not incremental
imports are supported from a particular foreign source depends on
the frontend program in use.
not contain the old commit).
--max-pack-size=<n>::
- Maximum size of each output packfile, expressed in MiB.
- The default is 4096 (4 GiB) as that is the maximum allowed
+ Maximum size of each output packfile.
+ The default is 4 GiB as that is the maximum allowed
packfile size (due to file format limitations). Some
importers may wish to lower this, such as to ensure the
resulting packfiles fit on CDs.
+--big-file-threshold=<n>::
+ Maximum size of a blob that fast-import will attempt to
+ create a delta for, expressed in bytes. The default is 512m
+ (512 MiB). Some importers may wish to lower this on systems
+ with constrained memory.
+
--depth=<n>::
Maximum delta depth, for blob and tree deltification.
Default is 10.
set of marks. If a mark is defined to different values,
the last file wins.
+--relative-marks::
+ After specifying --relative-marks= the paths specified
+ with --import-marks= and --export-marks= are relative
+ to an internal directory in the current repository.
+ In git-fast-import this means that the paths are relative
+ to the .git/info/fast-import directory. However, other
+ importers may use a different location.
+
+--no-relative-marks::
+ Negates a previous --relative-marks. Allows for combining
+ relative and non-relative marks by interweaving
+ --(no-)-relative-marks= with the --(import|export)-marks=
+ options.
+
--export-pack-edges=<file>::
After creating a packfile, print a line of data to
<file> listing the filename of the packfile and the last
This information may be useful after importing projects
whose total object set exceeds the 4 GiB packfile limit,
as these commits can be used as edge points during calls
- to 'git-pack-objects'.
+ to 'git pack-objects'.
--quiet::
Disable all non-fatal output, making fast-import silent when it
Parallel Operation
------------------
-Like 'git-push' or 'git-fetch', imports handled by fast-import are safe to
+Like 'git push' or 'git fetch', imports handled by fast-import are safe to
run alongside parallel `git repack -a -d` or `git gc` invocations,
-or any other Git operation (including 'git-prune', as loose objects
+or any other Git operation (including 'git prune', as loose objects
are never used by fast-import).
fast-import does not lock the branch or tag refs it is actively importing.
prints a warning message. fast-import will always attempt to update all
branch refs, and does not stop on the first failure.
-Branch updates can be forced with \--force, but its recommended that
+Branch updates can be forced with \--force, but it's recommended that
this only be used on an otherwise quiet repository. Using \--force
is not necessary for an initial import into an empty repository.
+
An example value is ``Tue Feb 6 11:22:18 2007 -0500''. The Git
parser is accurate, but a little on the lenient side. It is the
-same parser used by 'git-am' when applying patches
+same parser used by 'git am' when applying patches
received from email.
+
Some malformed strings may be accepted as valid dates. In some of
created by fast-import. There is no way to specify a different time or
timezone.
+
-This particular format is supplied as its short to implement and
+This particular format is supplied as it's short to implement and
may be useful to a process that wants to create a new commit
right now, without needing to use a working directory or
-'git-update-index'.
+'git update-index'.
+
If separate `author` and `committer` commands are used in a `commit`
the timestamps may not match, as the system clock will be polled
standard output. This command is optional and is not needed
to perform an import.
+`feature`::
+ Require that fast-import supports the specified feature, or
+ abort if it does not.
+
+`option`::
+ Specify any of the options listed under OPTIONS that do not
+ change stream semantic to suit the frontend's needs. This
+ command is optional and is not needed to perform an import.
+
`commit`
~~~~~~~~
Create or update a branch with a new commit, recording one logical
Here `<committish>` is any of the following:
* The name of an existing branch already in fast-import's internal branch
- table. If fast-import doesn't know the name, its treated as a SHA-1
+ table. If fast-import doesn't know the name, it's treated as a SHA-1
expression.
* A mark reference, `:<idnum>`, where `<idnum>` is the mark number.
complete set of bytes which normally goes into such a signature.
If signing is required, create lightweight tags from within fast-import with
`reset`, then create the annotated versions of those tags offline
-with the standard 'git-tag' process.
+with the standard 'git tag' process.
`reset`
~~~~~~~
The mark command is optional here as some frontends have chosen
to generate the Git SHA-1 for the blob on their own, and feed that
-directly to `commit`. This is typically more work than its worth
+directly to `commit`. This is typically more work than it's worth
however, as marks are inexpensive to store and easy to use.
`data`
inform the reader when the `checkpoint` has been completed and it
can safely access the refs that fast-import updated.
+`feature`
+~~~~~~~~~
+Require that fast-import supports the specified feature, or abort if
+it does not.
+
+....
+ 'feature' SP <feature> LF
+....
+
+The <feature> part of the command may be any string matching
+^[a-zA-Z][a-zA-Z-]*$ and should be understood by fast-import.
+
+Feature work identical as their option counterparts with the
+exception of the import-marks feature, see below.
+
+The following features are currently supported:
+
+* date-format
+* import-marks
+* export-marks
+* relative-marks
+* no-relative-marks
+* force
+
+The import-marks behaves differently from when it is specified as
+commandline option in that only one "feature import-marks" is allowed
+per stream. Also, any --import-marks= specified on the commandline
+will override those from the stream (if any).
+
+`option`
+~~~~~~~~
+Processes the specified option so that git fast-import behaves in a
+way that suits the frontend's needs.
+Note that options specified by the frontend are overridden by any
+options the user may specify to git fast-import itself.
+
+....
+ 'option' SP <option> LF
+....
+
+The `<option>` part of the command may contain any of the options
+listed in the OPTIONS section that do not change import semantics,
+without the leading '--' and is treated in the same way.
+
+Option commands must be the first commands on the input (not counting
+feature commands), to give an option command after any non-option
+command is an error.
+
+The following commandline options change import semantics and may therefore
+not be passed as option:
+
+* date-format
+* import-marks
+* export-marks
+* force
+
Crash Reports
-------------
If fast-import is supplied invalid input it will terminate with a
When committing fixups, consider using `merge` to connect the
commit(s) which are supplying file revisions to the fixup branch.
-Doing so will allow tools such as 'git-blame' to track
+Doing so will allow tools such as 'git blame' to track
through the real commit history and properly annotate the source
files.
~~~~~~~~~~~~~~~~~~~~~~~~~
If you are repacking very old imported data (e.g. older than the
last year), consider expending some extra CPU time and supplying
-\--window=50 (or higher) when you run 'git-repack'.
+\--window=50 (or higher) when you run 'git repack'.
This will take longer, but will also produce a smaller packfile.
You only need to expend the effort once, and everyone using your
project will benefit from the smaller repository.