[PATCH] Alphabetize the fast-import options, following a suggestion on the list.

[PATCH] Alphabetize the fast-import options, following a suggestion on the list.

[Eric S. Raymond]

---
 Documentation/git-fast-import.txt | 94 +++++++++++++++++++--------------------
 1 file changed, 45 insertions(+), 49 deletions(-)

diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 68bca1a..d006bcf 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -33,24 +33,9 @@ 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.
-
---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.
+--active-branches=<n>::
+	Maximum number of branches to maintain active at once.
+	See ``Memory Utilization'' below for details.  Default is 5.
 
 --big-file-threshold=<n>::
 	Maximum size of a blob that fast-import will attempt to
@@ -58,13 +43,27 @@ OPTIONS
 	(512 MiB).  Some importers may wish to lower this on systems
 	with constrained memory.
 
+--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.
+
+--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.
+
 --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.
+--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-marks=<file>::
 	Dumps the internal marks table to <file> when complete.
@@ -75,6 +74,20 @@ OPTIONS
 	at checkpoint (or completion) the same path can also be
 	safely given to \--import-marks.
 
+--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'.
+
+--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).
+
 --import-marks=<file>::
 	Before processing any input, load the marks specified in
 	<file>.  The input file must exist, must be readable, and
@@ -87,13 +100,9 @@ OPTIONS
 	Like --import-marks but instead of erroring out, silently
 	skips the file if it does not exist.
 
---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.
+--max-pack-size=<n>::
+	Maximum size of each output packfile.
+	The default is unlimited.
 
 --no-relative-marks::
 	Negates a previous --relative-marks. Allows for combining
@@ -101,32 +110,19 @@ OPTIONS
 	--(no-)-relative-marks with the --(import|export)-marks=
 	options.
 
---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.
-
---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'.
-
 --quiet::
 	Disable all non-fatal output, making fast-import silent when it
 	is successful.  This option disables the output shown by
 	\--stats.
 
+--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.
+
 --stats::
 	Display some basic statistics about the objects fast-import has
 	created, the packfiles they were stored into, and the
-- 
1.8.1



-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

"Gun control" is a job-safety program for criminals.

Re: [PATCH] Alphabetize the fast-import options, following a suggestion on the list.

[Jonathan Nieder]

Eric S. Raymond wrote:

> ---

Missing sign-off.  Depending on when you prefer to add the sign-off, something
like

	echo '[alias] c = commit --signoff' >>~/.gitconfig

or

	echo '[alias] f = format-patch --signoff' >>~/.gitconfig

might be useful for the future, assuming you already look over what
you are sending out in a mail client to avoid mistakes.

> Documentation/git-fast-import.txt | 94 +++++++++++++++++++--------------------
> 1 file changed, 45 insertions(+), 49 deletions(-)

My knee-jerk response was "If the options are currently organized logically,
wouldn't it be more appropriate to add a sub-heading for each group of options
and alphabetize only within the subgroups?"

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

Re: [PATCH] Alphabetize the fast-import options, following a suggestion on the list.

[Eric S. Raymond]

Jonathan Nieder <jrnieder@gmail.com>:
> But in fact the current options list doesn't seem to be well organized at all.

I agree.

> 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

That would work as well or better than any other organization I can
think of.  Um, which is significant because my work on surgery tools
and exporters means I've had to consult this page a *lot*.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [PATCH] Alphabetize the fast-import options, following a suggestion on the list.

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> My knee-jerk response was "If the options are currently organized logically,
> wouldn't it be more appropriate to add a sub-heading for each group of options
> and alphabetize only within the subgroups?"
>
> 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.

[PATCH] git-fast-import(1): reorganise options

[John Keeping]

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

[PATCH/RFC] fast-import doc: split OPTIONS into subsections

[Jonathan Nieder]

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

Re: [PATCH] git-fast-import(1): reorganise options

[Jonathan Nieder]

John Keeping wrote:

> How about this?

Ah, our patches crossed.

> I left the "Semantics of execution" options with the general options
> since I couldn't think of a sensible heading

Neat trick. :)

[...]
> -- <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.

Nice description.

> 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.

I'd prefer to keep those as separate patches, if that's manageable.

The organization you propose is:

	OPTIONS
	-------
	--quiet
	--stats
	--force
	--cat-blob-fd
	--export-pack-edges

	Options related to the input stream
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	--date-format
	--done

	Options related to marks
	~~~~~~~~~~~~~~~~~~~~~~~~
	--export-marks
	--import-marks
	--import-marks-if-exists
	--relative-marks
	--no-relative-marks

	Options for tuning
	~~~~~~~~~~~~~~~~~~
	--active-branches
	--big-file-threshold
	--depth
	--max-pack-size

These headings are less cryptic than the ones I proposed, which is a
nice thing.

My only nitpicks:

I'd worry that the catch-all toplevel category would grow larger
and larger with time, since it's the obvious place to put any new
option.

Part of what I tried to do with the proposed categorization was to
separate options that change the semantics of the import (which one
uses with "feature" when they are specified in the fast-import stream
since ignoring them results in a broken import) from options that only
change superficial aspects of the interface or the details of how the
resulting packfiles representing the same objects get written.

The phrasing of the name of the category "Options related to the input
stream" is too broad.  All options relate to the input stream, since
consuming an input stream and acting on it is all fast-import does.
Something more specific than "related to" and a mention of "syntax"
could make it clearer --- how about something like "Input Syntax
Features"?

Likewise, lots of functionality is _related_ to marks, but the marks
options are the options that specify marks files.  I don't know a good
way to say that --- maybe "Location of Marks Files"?

"Options for Tuning" could also be made more specific --- e.g.,
"Performance and Compression Tuning".

I like how you put important options like --force on top.  Perhaps
the less important --quiet and --stats could be split off from that
into a subsection like "Verbosity" to make them stand out even more.

Generally I think this is a better starting point for future work than
the patch I sent.  Thanks for writing it.

Jonathan

Re: [PATCH] git-fast-import(1): reorganise options

[John Keeping]

On Sun, Jan 06, 2013 at 05:51:09AM -0800, Jonathan Nieder wrote:
> John Keeping wrote:
>> I left the "Semantics of execution" options with the general options
>> since I couldn't think of a sensible heading
> 
> Neat trick. :)

I took inspiration from git-pull(1), which has a few general options
followed by several "Options related to..." sections.

> [...]
> > -- <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.
> 
> Nice description.
> 
> > 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.
> 
> I'd prefer to keep those as separate patches, if that's manageable.

I'll send a series of three patches if the discussion below seems
reasonable:

[1/3] remove duplicate '--done'
[2/3] combine --[no-]relative-marks
[3/3] reorganize options

> The organization you propose is:
> 
> 	OPTIONS
> 	-------
> 	--quiet
> 	--stats
> 	--force
> 	--cat-blob-fd
> 	--export-pack-edges
> 
> 	Options related to the input stream
> 	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> 	--date-format
> 	--done
> 
> 	Options related to marks
> 	~~~~~~~~~~~~~~~~~~~~~~~~
> 	--export-marks
> 	--import-marks
> 	--import-marks-if-exists
> 	--relative-marks
> 	--no-relative-marks
> 
> 	Options for tuning
> 	~~~~~~~~~~~~~~~~~~
> 	--active-branches
> 	--big-file-threshold
> 	--depth
> 	--max-pack-size
> 
> These headings are less cryptic than the ones I proposed, which is a
> nice thing.
> 
> My only nitpicks:
> 
> I'd worry that the catch-all toplevel category would grow larger
> and larger with time, since it's the obvious place to put any new
> option.

I agree that that's a concern, perhaps '--cat-blob-fd' should be
combined with '--date-format' and '--done' into a section called
"Options for frontends" or similar?

And maybe '--export-pack-edges' can move to the performance/compression
tuning section?  I expect the interested audience would be the same.

That only leaves three options in that section, which seems more
reasonable.

> Part of what I tried to do with the proposed categorization was to
> separate options that change the semantics of the import (which one
> uses with "feature" when they are specified in the fast-import stream
> since ignoring them results in a broken import) from options that only
> change superficial aspects of the interface or the details of how the
> resulting packfiles representing the same objects get written.
>
> The phrasing of the name of the category "Options related to the input
> stream" is too broad.  All options relate to the input stream, since
> consuming an input stream and acting on it is all fast-import does.
> Something more specific than "related to" and a mention of "syntax"
> could make it clearer --- how about something like "Input Syntax
> Features"?
> 
> Likewise, lots of functionality is _related_ to marks, but the marks
> options are the options that specify marks files.  I don't know a good
> way to say that --- maybe "Location of Marks Files"?
>
> "Options for Tuning" could also be made more specific --- e.g.,
> "Performance and Compression Tuning".

I realise it's personal taste, but I like the subheadings of the form
"Options (for|related to) ...", so maybe:

Options for input stream features
Options related to marks files
Options for performance and compression tuning

Note that I chose sentence case instead of title case to be consistent
with git-pull(1).

> I like how you put important options like --force on top.  Perhaps
> the less important --quiet and --stats could be split off from that
> into a subsection like "Verbosity" to make them stand out even more.

I quite like having the verbosity options near the top since those are
the ones that are most likely to be of interest to a user, whereas the
rest are likely to be prescribed by the frontend (or only really useful
to frontend authors).


John

Re: [PATCH] git-fast-import(1): reorganise options

[Junio C Hamano]

John Keeping <john@keeping.me.uk> writes:

> On Sun, Jan 06, 2013 at 05:51:09AM -0800, Jonathan Nieder wrote:
> ...
>> Nice description.
>> 
>> > 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.
>> 
>> I'd prefer to keep those as separate patches, if that's manageable.
>
> I'll send a series of three patches if the discussion below seems
> reasonable:
>
> [1/3] remove duplicate '--done'
> [2/3] combine --[no-]relative-marks
> [3/3] reorganize options

Sounds sensible and I like the direction in which this discussion is
progressing.

>> I'd worry that the catch-all toplevel category would grow larger
>> and larger with time, since it's the obvious place to put any new
>> option.
>
> I agree that that's a concern, perhaps '--cat-blob-fd' should be
> combined with '--date-format' and '--done' into a section called
> "Options for frontends" or similar?
>
> And maybe '--export-pack-edges' can move to the performance/compression
> tuning section?  I expect the interested audience would be the same.
>
> That only leaves three options in that section, which seems more
> reasonable.

I'll leave it to others to decide which individual options would
fall into that catch-all category, but the idea you outlined above
sounds sensible overall.

> I realise it's personal taste, but I like the subheadings of the form
> "Options (for|related to) ...", so maybe:
>
> Options for input stream features
> Options related to marks files
> Options for performance and compression tuning

Again, sounds sensible.

>> I like how you put important options like --force on top.  Perhaps
>> the less important --quiet and --stats could be split off from that
>> into a subsection like "Verbosity" to make them stand out even more.
>
> I quite like having the verbosity options near the top since those are
> the ones that are most likely to be of interest to a user, whereas the
> rest are likely to be prescribed by the frontend (or only really useful
> to frontend authors).

I tend to agree with Jonathan that verbosity options are less
important ones than the ones that affect how things work.

Thanks.

[PATCH v2 0/2] Reorganise options in git-fast-import(1)

[John Keeping]

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

[PATCH v2 1/2] git-fast-import(1): combine documentation of --[no-]relative-marks

[John Keeping]

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 <john@keeping.me.uk>
---
 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=<fd>::
 	Write responses to `cat-blob` and `ls` queries to the
-- 
1.8.1.468.g3d9f9b6

[PATCH v2 2/2] git-fast-import(1): reorganise options

[John Keeping]

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 <jrnieder@gmail.com>
Signed-off-by: John Keeping <john@keeping.me.uk>

---
 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=<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).
 
---max-pack-size=<n>::
-	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=<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.
+--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=<n>::
-	Maximum delta depth, for blob and tree deltification.
-	Default is 10.
+Options for Frontends
+~~~~~~~~~~~~~~~~~~~~~
 
---active-branches=<n>::
-	Maximum number of branches to maintain active at once.
-	See ``Memory Utilization'' below for details.  Default is 5.
+--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.
+
+--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.
+
+Locations of Marks Files
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 --export-marks=<file>::
 	Dumps the internal marks table to <file> 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=<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.
+--active-branches=<n>::
+	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=<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.
 
 --export-pack-edges=<file>::
 	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=<n>::
+	Maximum size of each output packfile.
+	The default is unlimited.
 
 
 Performance
-- 
1.8.1.468.g3d9f9b6

Re: [PATCH v2 1/2] git-fast-import(1): combine documentation of --[no-]relative-marks

[Jonathan Nieder]

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 <jrnieder@gmail.com>

Re: [PATCH v2 2/2] git-fast-import(1): reorganise options

[Junio C Hamano]

Thanks.