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

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Dec 27, 2023, 22:29 UTC
Message-ID: <CAPig+cShsSSd-jpvSW_sq3-R++zjtHU-m2PmTsz-Nx9YVRStug@mail.gmail.com>
In-Reply-To: <3d46bca1-96d4-43ba-a912-1f7c76942287@smtp-relay.sendinblue.com>

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.

Show 7 quoted lines

> Signed-off-by: Britton L Kerin <britton.kergin@gmail.com>
> ---
> 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?

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.