Re: [PATCH v2 3/6] parse-options: stop supporting "" in the usagestr array

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Sep 11, 2021, 02:46 UTC
Message-ID: <87r1dvaksr.fsf@evledraar.gmail.com>
In-Reply-To: <xmqqlf44otbz.fsf@gitster.g>

On Fri, Sep 10 2021, Junio C Hamano wrote:

Show 36 quoted lines

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>> The strings in the the "usagestr" array have special handling for the
>> empty string dating back to f389c808b67 (Rework make_usage to print
>> the usage message immediately, 2007-10-14).
>>
>> We'll prefix all strings after the first one with "or: ". Then if we
>> encountered a "" we'll emit all strings after that point verbatim
>> without any "or: " prefixing.
>>
>> This gets rid of that special case, which was added in
>> f389c808b67 (Rework make_usage to print the usage message immediately,
>> 2007-10-14). It was only used "blame" (the "credential-cache*" use of
>
> used *by* "blame"
>
>> it was removed in the preceding commit). Before this change we'd emit:
>>
>>     $ git blame -h
>>     usage: git blame [<options>] [<rev-opts>] [<rev>] [--] <file>
>>
>>         <rev-opts> are documented in git-rev-list(1)
>
> The most crucial information is missing.  It may be shared with the
> previous step but it is even worse in this step.
>
> Why is this loss of feature a desirable thing in the first place?
>
> What are we gaining by breaking the "after listing the alternative
> forms concatenated with 'or:', we can give a general description,
> before going onto the list of options"?
>
> Without that explained, the remainder of the proposed log message
> reads more like an excuse for breaking the feature, justifying that
> the loss of feature can be worked around, than the description of a
> solution.

Making it the same as how "git bundle" describes it doesn't seem anywhere close to breaking it, and that also goes to the point you had about brevity on another patch.

I think that passing custom or generated help advice here might make sense generally, i.e. we might eventually want to expand that to all built-in as part of improving the -h and --help output, see e.g. the note at the bottom of "git --help".

But if we do that let's do that with an API where we simply pass this custom string in as another parameter to the function, rather than having a state machine to parse it out of the array we use for the "usage:" and "or:" list of lines.