From: John Keeping <john@keeping.me.uk>
To: Junio C Hamano <gitster@pobox.com>
Cc: Jonathan Nieder <jrnieder@gmail.com>,
"Eric S. Raymond" <esr@thyrsus.com>,
git@vger.kernel.org, David Michael Barr <b@rr-dav.id.au>,
Pete Wyckoff <pw@padd.com>
Subject: [PATCH] git-fast-import(1): reorganise options
Date: Sun, 6 Jan 2013 13:29:15 +0000 [thread overview]
Message-ID: <20130106132915.GG6440@serenity.lan> (raw)
In-Reply-To: <7vy5g6okdi.fsf@alter.siamese.dyndns.org>
On Sat, Jan 05, 2013 at 11:12:25PM -0800, Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@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 <jrnieder@gmail.com>
Signed-off-by: John Keeping <john@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
next prev parent reply other threads:[~2013-01-06 13:29 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-01-05 16:44 [PATCH] Alphabetize the fast-import options, following a suggestion on the list Eric S. Raymond
2013-01-05 23:11 ` Jonathan Nieder
2013-01-06 5:13 ` Eric S. Raymond
2013-01-06 7:12 ` Junio C Hamano
2013-01-06 13:29 ` John Keeping [this message]
2013-01-06 13:51 ` [PATCH] git-fast-import(1): reorganise options Jonathan Nieder
2013-01-06 14:28 ` John Keeping
2013-01-06 23:10 ` Junio C Hamano
2013-01-09 19:43 ` [PATCH v2 0/2] Reorganise options in git-fast-import(1) John Keeping
2013-01-09 19:44 ` [PATCH v2 1/2] git-fast-import(1): combine documentation of --[no-]relative-marks John Keeping
2013-01-09 21:42 ` Jonathan Nieder
2013-01-09 19:45 ` [PATCH v2 2/2] git-fast-import(1): reorganise options John Keeping
2013-01-09 22:21 ` Junio C Hamano
2013-01-06 13:34 ` [PATCH/RFC] fast-import doc: split OPTIONS into subsections Jonathan Nieder
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20130106132915.GG6440@serenity.lan \
--to=john@keeping.me.uk \
--cc=b@rr-dav.id.au \
--cc=esr@thyrsus.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jrnieder@gmail.com \
--cc=pw@padd.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).