Re: [PATCH 1/1] doc: use singular form of repeatable path arg

Junio C Hamano
2023-12-28T00:10:57Z

Eric Sunshine <sunshine@sunshineco.com> writes:

> On Wed, Dec 27, 2023 at 3:55 PM Britton Leo Kerin
> <britton.kerin@gmail.com> wrote:
>> This is more correct because the <path>... doc syntax already indicates
>> that the arg is "array-type". It's how other tools do it. Finally, the
>> later document text mentions 'path' arguments, while it doesn't mention
>> 'paths'.
>
> Yep, makes sense.
>
>> Signed-off-by: Britton L Kerin <britton.kergin@gmail.com>

Micronit. This should be identical to how From: line identifies the
author. s/L/Leo/ should be sufficient, I presume?

>> ---
>> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
>> @@ -17,7 +17,7 @@ The command takes various subcommands, and different options depending
>> git bisect start [--term-(new|bad)=<term-new> --term-(old|good)=<term-old>]
>> - [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...]
>> + [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<path>...]
>
> Looking good.
>
> In builtin/bisect.c, the "usage" string says "[<pathspec>...]" rather
> than "[<path>...]". Perhaps it makes sense to unify these?

Yup, and that would be a good thing to do in a single patch, and
also it would be a good place to stop. Further clean-up you
suggested below are very much worth doing, but it probably is good
to leave out of this single focused fix we are reviewing here and
instead be done as separate patch(es).

Thanks.

> Also, there are a few more documentation files that could use the
> "<paths>" to "<path>..." fixup (though not always in the synopsis). A
> 'grep' indicates that git-checkout.txt, git-diff.txt, and
> git-rev-list-options.txt also mention "<paths>". Those may be outside
> the scope of this patch, although they could easily be included, as
> well, or made part of a patch series if you feel inclined.