On Sat, Jan 05, 2013 at 11:12:25PM -0800, Junio C Hamano wrote:
> Jonathan Nieder <jrnie...@gmail.com> writes:
>> But in fact the current options list doesn't seem to be well organized at 
>> all.
>> What do you think would be a logical way to group these?
>>
>>  Features of input syntax
>>
>>      --date-format
>>      --done
>>
>>  Verbosity
>>
>>      --quiet
>>      --stats
>>
>>  Marks handling (checkpoint/restore)
>>
>>      --import-marks
>>      --import-marks-if-exists
>>      --export-marks
>>      --relative-marks
>>
>>  Semantics of execution
>>
>>      --dry-run
>>      --force
>>      --cat-blob-fd
>>      --export-pack-edges
>>
>>  Tuning
>>
>>      --active-branches
>>      --max-pack-size
>>      --big-file-threshold
>>      --depth
> 
> Sounds sensible.

How about this?

I left the "Semantics of execution" options with the general options
since I couldn't think of a sensible heading that didn't also apply to
'--quiet' or '--stats', but I think the result is reasonable.

-- <8 --

The options in git-fast-import(1) are not currently arranged in a
logical order, which has caused the '--done' options to be documented
twice (commit 3266de10).

Rearrange them into logical groups under subheadings.

While doing this, fix the duplicate '--done' documentation by taking the
best bits of each.  Also combine the descriptions of '--relative-marks'
and '--no-relative-marks' since they make more sense together.

Suggested-by: Jonathan Nieder <jrnie...@gmail.com>
Signed-off-by: John Keeping <j...@keeping.me.uk>
---
 Documentation/git-fast-import.txt | 115 +++++++++++++++++++-------------------
 1 file changed, 59 insertions(+), 56 deletions(-)

diff --git a/Documentation/git-fast-import.txt 
b/Documentation/git-fast-import.txt
index 68bca1a..0e25c8d 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -33,38 +33,55 @@ the frontend program in use.
 
 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.
 
--- done::
-       Terminate with error if there is no 'done' command at the
-       end of the stream.
+--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.
 
 --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.
+--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.
 
---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.
+--export-pack-edges=<file>::
+       After creating a packfile, print a line of data to
+       <file> listing the filename of the packfile and the last
+       commit on each branch that was written to that packfile.
+       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'.
 
---depth=<n>::
-       Maximum delta depth, for blob and tree deltification.
-       Default is 10.
+Options related to the input stream
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
---active-branches=<n>::
-       Maximum number of branches to maintain active at once.
-       See ``Memory Utilization'' below for details.  Default is 5.
+--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.
+
+Options related to marks
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 --export-marks=<file>::
        Dumps the internal marks table to <file> when complete.
@@ -87,51 +104,37 @@ OPTIONS
        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.
+Options for tuning
+~~~~~~~~~~~~~~~~~~
 
---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.
-
---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.
+--active-branches=<n>::
+       Maximum number of branches to maintain active at once.
+       See ``Memory Utilization'' below for details.  Default is 5.
 
---export-pack-edges=<file>::
-       After creating a packfile, print a line of data to
-       <file> listing the filename of the packfile and the last
-       commit on each branch that was written to that packfile.
-       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'.
+--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.
 
---quiet::
-       Disable all non-fatal output, making fast-import silent when it
-       is successful.  This option disables the output shown by
-       \--stats.
+--depth=<n>::
+       Maximum delta depth, for blob and tree deltification.
+       Default is 10.
 
---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
-- 
1.8.0.2

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to