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

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Jan 6, 2013, 13:51 UTC
Message-ID: <20130106135109.GF22081@elie.Belkin>
In-Reply-To: <20130106132915.GG6440@serenity.lan>

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

[...]

Show 6 quoted lines

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