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

From: Junio C Hamano <[email-masked]>
Date: Mon, 03 Oct 2022 08:55:58 -0700

Ævar Arnfjörð Bjarmason <[email-masked]> writes:

> On Sat, Oct 01 2022, Junio C Hamano wrote:
>
>> Ævar Arnfjörð Bjarmason  <[email-masked]> 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>".

Not really.  A <pathspec> is a set of <pathspec element>s, so
writing "<pathspec-element>..." and "<pathspec>" are equivalent.

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

Presumably just like range-diff compares two ranges (which in the
normal command line syntax we would not have), some future commands
may need to take two pathspecs (that is two sets of patterns to
match paths) to do something interesting, but I do not think of
anything that does so in the current command set, so it is very good
that nobody claims to take <pathspecs> with an "s"for plural.

> 	Documentation/git-clone.txt:--recurse-submodules[=<pathspec>]::
>
> Should be read as supporting:
>
> 	--recurse-submodules some/path some-other-path

Yup, the option should support it, alternatively it could take
<path>.  Or it could take multiple of these options in which case
each of them is taking a pathspec element.