Instead of going over the patches in the rest of the series, I think
we'd probably need to step back a bit and give ourselves a general
guideline.
This list is a draft of things I have learned from reading the
series, many of them from this step 21/36 alone, but some are from
earlier steps. I think the ones with '*' in front of them are not
controversial, but others are merely my suggestions at this point:
* Use of spaces in optional [] and choose-from-one, both for
freestanding token and for a value (i.e. what immediately follows
an equal sign '='), are as specified in [PATCH 1/36].
* For a command "git cmd", the documentation in the SYNOPSIS
section and the usage string from "git cmd -h" ought to match.
Let's call them simply a "usage string".
* The usage string for a command that has majorly different
operating modes can and should enumerate the different forms
separately (cf. how "git diff -h" lists different modes).
* The usage string for a command with a large number of options can
and should use "[<options>]" placeholder in the SYNOPSIS and
"usage:" lines, i.e. "git cmd [<options>]", and let the
DESCRIPTION section (in documentation) and the option listing (in
the output from usage_with_options() function).
+ The usage string for a command with a small number of options can
enumerate individual options as long as the result (for each
operating modes) can fit on a single line.
+ When a usage string shows options individually (instead of using
[<options>] placeholder and leaving the listing to the latter
half of usage_with_options()):
- if an option has both long and short forms, only long form can
and should be shown if the resulting line would become overly
long with both listed as choices.
do : "git cmd [--quiet] [--verbose] [--dry-run] <pathspec>"
don't: "git cmd [--quiet | -q] [--verbose | -v] [--dry-run | -n] <pathspec>"
- when showing a Boolean option, show only the form that
countermands the default, unless the command can take a
different default depending on the context. When use of other
options or configuration can change the default value, show the
option as "--[no-]option".
do : "git pack-refs [--all] [--no-prune]"
don't: "git pack-refs [--[no-]all] [--[no-]prune]"
- when showing an option that can be given multiple times that
causes cumulative effect (as opposed to the "last one wins"),
signal that by saying "--option..." to signal that it is
meaningful to have one or more of them.
