The OPTIONS section of this manpage has grown long without any
particular organization to ensure it remains manageable. Split into
categories to make the documentation for each option easier to find.
The categories:
1. Features of the input format, such as the date format and whether
the file is required to end with a "done" command.
2. How much output the importer should write to stderr.
3. Marks Handling (Checkpoint/Restart).
4. Other options that change the behavior in a semantically
meaningful way (backflow pipe setup, whether to force ref
updates, where to list pack edges).
5. Performance and compression tuning.
Reported-by: John Keeping <john@xxxxxxxxxxxxx>
Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx>
---
The second-to-last subsection ("Import Semantics") is kind of a
catch-all. Better ideas for organization or naming would be
welcome.
Documentation/git-fast-import.txt | 82 ++++++++++++++++++++++-----------------
1 file changed, 46 insertions(+), 36 deletions(-)
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index d2c0e357..1676d436 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -32,35 +32,36 @@ the frontend program in use.
OPTIONS
-------
+Input Syntax
+~~~~~~~~~~~~
--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).
+--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.
---max-pack-size=<n>::
- Maximum size of each output packfile.
- The default is unlimited.
+Verbosity
+~~~~~~~~~
+--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.
-
---depth=<n>::
- Maximum delta depth, for blob and tree deltification.
- Default is 10.
-
---active-branches=<n>::
- Maximum number of branches to maintain active at once.
- See ``Memory Utilization'' below for details. Default is 5.
+--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.
+Marks Handling (Checkpoint/Restart)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--export-marks=<file>::
Dumps the internal marks table to <file> when complete.
Marks are written one per line as `:markid SHA-1`.
@@ -96,18 +97,18 @@ OPTIONS
--(no-)-relative-marks with the --(import|export)-marks=
options.
+Import Semantics
+~~~~~~~~~~~~~~~~
+--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).
+
--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`.
---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.
-
--export-pack-edges=<file>::
After creating a packfile, print a line of data to
<file> listing the filename of the packfile and the last
@@ -117,16 +118,25 @@ OPTIONS
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.
+Tuning
+~~~~~~
+--max-pack-size=<n>::
+ Maximum size of each output packfile.
+ The default is unlimited.
---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.
+--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.
+
+--active-branches=<n>::
+ Maximum number of branches to maintain active at once.
+ See ``Memory Utilization'' below for details. Default is 5.
Performance
--
1.8.1
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html