Re: [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Oct 3, 2022, 09:00 UTC
Message-ID: <221003.86sfk5tgrs.gmgdl@evledraar.gmail.com>
In-Reply-To: <xmqqmtaf2xig.fsf@gitster.g>

On Sat, Oct 01 2022, Junio C Hamano wrote:

Show 8 quoted lines

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>> For "rerere" say "pathspec" consistently, and list the subcommands in
>> the order that they're discussed in the "COMMANDS" section of the
>> documentation.
>
> pathspec refers to the entire set of patterns, which consists of one
> or more "pathspec element"s, so there is no need for "..." there.

Maybe I'm misreading this, but are you suggesting that whenever "<pathspec>" appears in the text the user should understand it as "<pathspec>...", i.e. as is the case with the special-case that is "<options>".

I'm not opposet do that, but I really wish we could avoid further special-cases, there's no current user of "<pathspecs>" (with an "s" for plural.

If you're saying that "<pathspec>" now should be interpretet like that then surely e.g.:

	Documentation/git-clone.txt:--recurse-submodules[=<pathspec>]::

Should be read as supporting:

	--recurse-submodules some/path some-other-path

We could say that using it in that option context is a further special-case, but I think this way lies madness, it would mean that e.g.:

	git some-cmd [--option=<pathspec>] [-- <pathspec>]

would have "<pathspec>" mean different things in those two contexts.

We also have various examples of "<pathspec>..." meaning what it means in the post-image here (including in one of the version of the "rerere" docs):

	Documentation/git-add.txt:        [--] [<pathspec>...]
	Documentation/git-commit.txt:      [--] [<pathspec>...]
	Documentation/git-reset.txt:'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]

FWIW it should arguably be [<pathspec>...] here, but per 5d2c3b01604 (rerere forget: deprecate invocation without pathspec, 2011-03-01) it looks as though we want to advertise the other usage.