Re: [PATCH] doc/git-bisect: clarify `git bisect run` syntax

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 23, 2023, 17:23 UTC
Message-ID: <xmqqsf61ntg4.fsf@gitster.g>
In-Reply-To: <ZTYi55w_70ZlP8Ew@tanuki>

Patrick Steinhardt <ps@pks.im> writes:

Show 9 quoted lines

>> 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.
>
> If we don't want them to drift apart I wonder whether we could instead
> generate the synopsis from the output of `-h`? This reduces duplication
> at the cost of a more complex build process for our manpages.

There also is the cost of making it unusable to peek the source git-foo.txt files as a quick way to get the usage guide, which I think is a downside only felt by developers of Git (not developers of other projects that happen to use Git), but still a downside.

But aside from that, it is an obviously possible direction to go [*] and in fact I suspect we may have talked about it when Ævar made a gigantic effort to clean these up in Sep-Oct 2022 timeframe, which resulted in the series leading to a0343f30 (tests: assert consistent whitespace in -h output, 2022-10-13) [*].

[Footnote]

 * And another possibility is to go from the doc to the message
   string, which may be even more involved, but at least the code
   needs to go through the build process anyway, so the downside
   might be lessor)

 * https://lore.kernel.org/git/patch-v5-34.34-4de83d3d89a-20221013T153626Z-avarab@gmail.com/