OPTIONS
-------
---date-format=<fmt>::
- Specify the type of dates the frontend will supply to
- fast-import within `author`, `committer` and `tagger` commands.
- See ``Date Formats'' below for details about which formats
- are supported, and their syntax.
--force::
Force updating modified existing branches, even if doing
so would cause commits to be lost (as the new commit does
not contain the old commit).
---max-pack-size=<n>::
- Maximum size of each output packfile.
- The default is unlimited.
+--quiet::
+ Disable all non-fatal output, making fast-import silent when it
+ is successful. This option disables the output shown by
+ \--stats.
---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.
+--stats::
+ Display some basic statistics about the objects fast-import has
+ created, the packfiles they were stored into, and the
+ memory used by fast-import during this run. Showing this output
+ is currently the default, but can be disabled with \--quiet.
---depth=<n>::
- Maximum delta depth, for blob and tree deltification.
- Default is 10.
+Options for Frontends
+~~~~~~~~~~~~~~~~~~~~~
---active-branches=<n>::
- Maximum number of branches to maintain active at once.
- See ``Memory Utilization'' below for details. Default is 5.
+--cat-blob-fd=<fd>::
+ Write responses to `cat-blob` and `ls` queries to the
+ file descriptor <fd> instead of `stdout`. Allows `progress`
+ output intended for the end-user to be separated from other
+ output.
+
+--date-format=<fmt>::
+ Specify the type of dates the frontend will supply to
+ fast-import within `author`, `committer` and `tagger` commands.
+ See ``Date Formats'' below for details about which formats
+ are supported, and their syntax.
+
+--done::
+ Terminate with error if there is no `done` command at the end of
+ the stream. This option might be useful for detecting errors
+ that cause the frontend to terminate before it has started to
+ write a stream.
+
+Locations of Marks Files
+~~~~~~~~~~~~~~~~~~~~~~~~
--export-marks=<file>::
Dumps the internal marks table to <file> when complete.
Like --import-marks but instead of erroring out, silently
skips the file if it does not exist.
---relative-marks::
+--[no-]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.
++
+Relative and non-relative marks may be combined by interweaving
+--(no-)-relative-marks with the --(import|export)-marks= options.
---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.
+Performance and Compression Tuning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---cat-blob-fd=<fd>::
- Specify the file descriptor that will be written to
- when the `cat-blob` command is encountered in the stream.
- The default behaviour is to write to `stdout`.
+--active-branches=<n>::
+ Maximum number of branches to maintain active at once.
+ See ``Memory Utilization'' below for details. Default is 5.
---done::
- Require a `done` command at the end of the stream.
- This option might be useful for detecting errors that
- cause the frontend to terminate before it has started to
- write a stream.
+--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.
--export-pack-edges=<file>::
After creating a packfile, print a line of data to
as these commits can be used as edge points during calls
to 'git pack-objects'.
---quiet::
- Disable all non-fatal output, making fast-import silent when it
- is successful. This option disables the output shown by
- \--stats.
-
---stats::
- Display some basic statistics about the objects fast-import has
- created, the packfiles they were stored into, and the
- memory used by fast-import during this run. Showing this output
- is currently the default, but can be disabled with \--quiet.
+--max-pack-size=<n>::
+ Maximum size of each output packfile.
+ The default is unlimited.
Performance
Here `<name>` is the person's display name (for example
``Com M Itter'') and `<email>` is the person's email address
-(``cm@example.com''). `LT` and `GT` are the literal less-than (\x3c)
+(``\cm@example.com''). `LT` and `GT` are the literal less-than (\x3c)
and greater-than (\x3e) symbols. These are required to delimit
the email address from the other fields in the line. Note that
`<name>` and `<email>` are free-form and may contain any sequence
^^^^^^
The `from` command is used to specify the commit to initialize
this branch from. This revision will be the first ancestor of the
-new commit.
+new commit. The state of the tree built at this commit will begin
+with the state at the `from` commit, and be altered by the content
+modifications in this commit.
Omitting the `from` command in the first commit of a new branch
will cause fast-import to create that commit with no ancestor. This
`merge`
^^^^^^^
-Includes one additional ancestor commit. If the `from` command is
+Includes one additional ancestor commit. The additional ancestry
+link does not change the way the tree state is built at this commit.
+If the `from` command is
omitted when creating a new branch, the first `merge` commit will be
the first ancestor of the current commit, and the branch will start
out with no files. An unlimited number of `merge` commands per
slash `/`), may contain any byte other than `LF`, and must not
start with double quote (`"`).
-If an `LF` or double quote must be encoded into `<path>` shell-style
-quoting should be used, e.g. `"path/with\n and \" in it"`.
+A path can use C-style string quoting; this is accepted in all cases
+and mandatory if the filename starts with double quote or contains
+`LF`. In C-style quoting, the complete name should be surrounded with
+double quotes, and any `LF`, backslash, or double quote characters
+must be escaped by preceding them with a backslash (e.g.,
+`"path/with\n, \\ and \" in it"`).
The value of `<path>` must be in canonical form. That is it must not:
accepted. In particular, the `cat-blob` command can be used in the
middle of a commit but not in the middle of a `data` command.
+See ``Responses To Commands'' below for details about how to read
+this output safely.
+
`ls`
~~~~
Prints information about the object at a path to a file descriptor
missing SP <path> LF
====
+See ``Responses To Commands'' below for details about how to read
+this output safely.
+
`feature`
~~~~~~~~~
Require that fast-import supports the specified feature, or abort if
Error out if the stream ends without a 'done' command.
Without this feature, errors causing the frontend to end
abruptly at a convenient point in the stream can go
- undetected.
+ undetected. This may occur, for example, if an import
+ front end dies in mid-operation without emitting SIGTERM
+ or SIGKILL at its subordinate git fast-import instance.
`option`
~~~~~~~~
in use, the `done` command is mandatory and marks the end of the
stream.
+Responses To Commands
+---------------------
+New objects written by fast-import are not available immediately.
+Most fast-import commands have no visible effect until the next
+checkpoint (or completion). The frontend can send commands to
+fill fast-import's input pipe without worrying about how quickly
+they will take effect, which improves performance by simplifying
+scheduling.
+
+For some frontends, though, it is useful to be able to read back
+data from the current repository as it is being updated (for
+example when the source material describes objects in terms of
+patches to be applied to previously imported objects). This can
+be accomplished by connecting the frontend and fast-import via
+bidirectional pipes:
+
+====
+ mkfifo fast-import-output
+ frontend <fast-import-output |
+ git fast-import >fast-import-output
+====
+
+A frontend set up this way can use `progress`, `ls`, and `cat-blob`
+commands to read information from the import in progress.
+
+To avoid deadlock, such frontends must completely consume any
+pending output from `progress`, `ls`, and `cat-blob` before
+performing writes to fast-import that might block.
+
Crash Reports
-------------
If fast-import is supplied invalid input it will terminate with a