# [PATCH v2 1/2] git-fast-import(1): combine documentation of --[no-]relative-marks 5 messages from 2013-01-09 to 2013-01-09. Participants: John Keeping, Jonathan Nieder, Junio C Hamano. Thread: https://gitlist.dev/t/32577 ## John Keeping, 2013-01-09 19:43 Subject: [PATCH v2 0/2] Reorganise options in git-fast-import(1) Message-ID: URL: https://gitlist.dev/e/cover.1357760256.git.john%40keeping.me.uk In-Reply-To: <7va9slnc07.fsf@alter.siamese.dyndns.org> ``` Here's a second attempt at this taking into account the feedback received so far. Changes since v1: * Left dedup '--done' as a separate patch (now merged) * Split combining '--[no-]relative-marks' into a separate patch * '--force' moved to the top of the options, making the catchall section alphabetically sorted * Section headings changed: 'Options related to the input stream' => 'Options for Frontends' 'Options related to marks' => 'Locations of Marks Files' 'Options for tuning' => 'Performance and Compression Tuning' * '--export-pack-edges' moves to 'Performance and Compression Tuning' * '--cat-blob-fd' moves to 'Options for Frontends' John Keeping (2): git-fast-import(1): combine documentation of --[no-]relative-marks git-fast-import(1): reorganise options Documentation/git-fast-import.txt | 98 +++++++++++++++++++++------------------ 1 file changed, 52 insertions(+), 46 deletions(-) -- 1.8.1.468.g3d9f9b6 ``` ## John Keeping, 2013-01-09 19:44 Subject: [PATCH v2 1/2] git-fast-import(1): combine documentation of --[no-]relative-marks Message-ID: URL: https://gitlist.dev/e/cf4a4a10c1de73491048e8283582bdbf8c79c75e.1357760256.git.john%40keeping.me.uk In-Reply-To: ``` The descriptions of '--relative-marks' and '--no-relative-marks' make more sense when read together instead of as two independent options. Combine them into a single description block. Signed-off-by: John Keeping --- Documentation/git-fast-import.txt | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 3da5cc2..75ce808 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -83,19 +83,17 @@ 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. --cat-blob-fd=:: Write responses to `cat-blob` and `ls` queries to the -- 1.8.1.468.g3d9f9b6 ``` ## John Keeping, 2013-01-09 19:45 Subject: [PATCH v2 2/2] git-fast-import(1): reorganise options Message-ID: URL: https://gitlist.dev/e/e228dd4522dbf7ebfe0e5207b1dcc9591faa4d15.1357760256.git.john%40keeping.me.uk In-Reply-To: ``` 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. Suggested-by: Jonathan Nieder Signed-off-by: John Keeping --- Documentation/git-fast-import.txt | 88 +++++++++++++++++++++------------------ 1 file changed, 48 insertions(+), 40 deletions(-) diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 75ce808..bf1a02a 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -33,34 +33,46 @@ the frontend program in use. OPTIONS ------- ---date-format=:: - 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=:: - 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=:: - 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=:: - Maximum delta depth, for blob and tree deltification. - Default is 10. +Options for Frontends +~~~~~~~~~~~~~~~~~~~~~ ---active-branches=:: - Maximum number of branches to maintain active at once. - See ``Memory Utilization'' below for details. Default is 5. +--cat-blob-fd=:: + Write responses to `cat-blob` and `ls` queries to the + file descriptor instead of `stdout`. Allows `progress` + output intended for the end-user to be separated from other + output. + +--date-format=:: + 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=:: Dumps the internal marks table to when complete. @@ -94,19 +106,22 @@ OPTIONS Relative and non-relative marks may be combined by interweaving --(no-)-relative-marks with the --(import|export)-marks= options. +Performance and Compression Tuning +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---cat-blob-fd=:: - Write responses to `cat-blob` and `ls` queries to the - file descriptor instead of `stdout`. Allows `progress` - output intended for the end-user to be separated from other - output. +--active-branches=:: + Maximum number of branches to maintain active at once. + See ``Memory Utilization'' below for details. Default is 5. ---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. +--big-file-threshold=:: + 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=:: + Maximum delta depth, for blob and tree deltification. + Default is 10. --export-pack-edges=:: After creating a packfile, print a line of data to @@ -117,16 +132,9 @@ Relative and non-relative marks may be combined by interweaving 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=:: + Maximum size of each output packfile. + The default is unlimited. Performance -- 1.8.1.468.g3d9f9b6 ``` ## Jonathan Nieder, 2013-01-09 21:42 Subject: Re: [PATCH v2 1/2] git-fast-import(1): combine documentation of --[no-]relative-marks Message-ID: <20130109214246.GA21054@google.com> URL: https://gitlist.dev/e/20130109214246.GA21054%40google.com In-Reply-To: ``` John Keeping wrote: > The descriptions of '--relative-marks' and '--no-relative-marks' make > more sense when read together instead of as two independent options. > Combine them into a single description block. Yep, this is easier to read. Thanks. Reviewed-by: Jonathan Nieder ``` ## Junio C Hamano, 2013-01-09 22:21 Subject: Re: [PATCH v2 2/2] git-fast-import(1): reorganise options Message-ID: <7v1udu3sl4.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7v1udu3sl4.fsf%40alter.siamese.dyndns.org In-Reply-To: ``` Thanks. ```