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

[Jonathan Nieder <jrnieder@gmail.com>]

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