From: Jonathan Nieder <jrnieder@gmail.com>
To: git@vger.kernel.org
Cc: John Keeping <john@keeping.me.uk>,
"Eric S. Raymond" <esr@thyrsus.com>,
David Michael Barr <b@rr-dav.id.au>, Pete Wyckoff <pw@padd.com>,
Thomas Rast <trast@student.ethz.ch>
Subject: [PATCH/RFC] fast-import doc: split OPTIONS into subsections
Date: Sun, 6 Jan 2013 05:34:15 -0800 [thread overview]
Message-ID: <20130106133415.GE22081@elie.Belkin> (raw)
In-Reply-To: <20130105231151.GD3247@elie.Belkin>
The OPTIONS section of this manpage has grown long without any
particular organization to ensure it remains manageable. Split into
categories to make the documentation for each option easier to find.
The categories:
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
prev parent reply other threads:[~2013-01-06 13:36 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 ` [PATCH] git-fast-import(1): reorganise options John Keeping
2013-01-06 13:51 ` 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 ` Jonathan Nieder [this message]
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=20130106133415.GE22081@elie.Belkin \
--to=jrnieder@gmail.com \
--cc=b@rr-dav.id.au \
--cc=esr@thyrsus.com \
--cc=git@vger.kernel.org \
--cc=john@keeping.me.uk \
--cc=pw@padd.com \
--cc=trast@student.ethz.ch \
/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).