From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 23 Oct 2023 00:35:41 GMT
Subject: Re: [PATCH] doc/git-bisect: clarify `git bisect run` syntax
Message-ID: <xmqqa5sap44i.fsf@gitster.g>
In-Reply-To: <CAPig+cS4J-L44a-fjQ=2bXxRj6e1qdQK8705K3NPqmTsWXBQsw@mail.gmail.com>

Eric Sunshine <sunshine@sunshineco.com> writes:

> On Sun, Oct 22, 2023 at 4:03 PM cousteau via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>> The description of the `git bisect run` command syntax at the beginning
>> of the manpage is `git bisect run <cmd>...`, which isn't quite clear
>> about what `<cmd>` is or what the `...` mean; one could think that it is
>> the whole (quoted) command line with all arguments in a single string,
>> or that it supports multiple commands, or that it doesn't accept
>> commands with arguments at all.
>>
>> Change to `git bisect run <cmd> [<arg>...]` to clarify the syntax.
>
> Okay, makes sense.
>
>> Signed-off-by: Javier Mora <cousteaulecommandant@gmail.com>
>> ---
>> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
>> @@ -26,7 +26,7 @@ on the subcommand:
>> - git bisect run <cmd>...
>> + git bisect run <cmd> [<arg>...]
>
> The output of `git bisect -h` suffers the same problem. Perhaps this
> patch can fix that, as well?

Good eyes.

Not a new problem and obviously can be left outside of this simple
update, but I wonder if we should eventually move these into the
proper SYNOPSIS section.  Other multi-modal commands like "git
checkout", "git rebase", etc. do list different forms all in the
SYNOPSIS section.

I also thought at least some commands we know the "-h" output and
SYNOPSIS match, we had tests to ensure they do not drift apart.  We
would probably want to cover more subcommands with t0450.

Thanks.