From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Mon, 03 Oct 2022 09:00:28 GMT
Subject: Re: [PATCH v3 22/36] doc txt & -h consistency: make "rerere" consistent
Message-ID: <221003.86sfk5tgrs.gmgdl@evledraar.gmail.com>
In-Reply-To: <xmqqmtaf2xig.fsf@gitster.g>


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

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