On Sat, Jan 05, 2013 at 11:12:25PM -0800, Junio C Hamano wrote: > Jonathan Nieder <jrnieder@xxxxxxxxx> 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 <jrnieder@xxxxxxxxx> Signed-off-by: John Keeping <john@xxxxxxxxxxxxx> --- 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 majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html