[PATCH/RFC] fast-import doc: split OPTIONS into subsections

From

Jonathan Nieder <jrnieder@gmail.com>

Date

Jan 6, 2013, 13:34 UTC

Message-ID

<20130106133415.GE22081@elie.Belkin>

In-Reply-To

<20130105231151.GD3247@elie.Belkin>

 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@keeping.me.uk>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
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