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

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Sun, Sep 12 2021, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>> diff --git a/t/t0040-parse-options.sh b/t/t0040-parse-options.sh
>> index ad4746d899a..2910874ece5 100755
>> --- a/t/t0040-parse-options.sh
>> +++ b/t/t0040-parse-options.sh
>> @@ -10,8 +10,6 @@ test_description='our own option parser'
>>  cat >expect <<\EOF
>>  usage: test-tool parse-options <options>
>>  
>> -    A helper function for the parse-options API.
>> -
>>      --yes                 get a boolean
>>      -D, --no-doubt        begins with 'no-'
>>      -B, --no-fear         be brave
>
> Isn't this, and a lot more importantly the next one ...
>
>> diff --git a/t/t1502-rev-parse-parseopt.sh b/t/t1502-rev-parse-parseopt.sh
>> index b29563fc997..6badc650d64 100755
>> --- a/t/t1502-rev-parse-parseopt.sh
>> +++ b/t/t1502-rev-parse-parseopt.sh
>> @@ -6,8 +6,6 @@ test_description='test git rev-parse --parseopt'
>>  test_expect_success 'setup optionspec' '
>>  	sed -e "s/^|//" >optionspec <<\EOF
>>  |some-command [options] <args>...
>> -|
>> -|some-command does foo and bar!
>>  |--
>>  |h,help    show the help
>>  |
>
> ... coalmine canaries that tell us that end-user's scripts using the
> "git rev-parse --parseopt" in the documented way will be broken?
>
> I'd rather not have to sorry about breaking end-user scripts this
> way.  Unlike a very small number of in-tree parse_options() call in
> C programs, we have unbounded of them.

I re-rolled this in v4 to not change how the function works at all:
https://lore.kernel.org/git/cover-v4-0.4-00000000000-20210912T235347Z-avarab@gmail.com/

I do think we're going above & beyond what's reasonable in maintaining
these interfaces, i.e. per 21d47835386 (Add a parseopt mode to
git-rev-parse to bring parse-options to shell scripts., 2007-11-04) I
don't think anyone thought that interface would be used outside of
git.git.

But then perhaps I'm wrong, or it has been, and since we ended up
sticking it in rev-parse which was marked as plumbing we can't change
how it or the underlying C APIs it relies on work.

In practice I doubt it would break things for anyone, but per the result
of the discussion to "remove dead shell code" [1] I don't think I'll get
anywhere with that.

I do think that getting some answer to [2] & how we think about the
likes of "git rev-parse --parseopt" going forward would be very
useful.

I.e. would you be OK with us marking these as deprecated / warn on their
out-of-tree use? If so we could after some time remove a lot of code &
simplify things once the last in-tree shellscript user goes away.

Or if we don't see that they can ever be changed that's also useful to
know (and per [2] I think I'd feel obligated to send in a revert
bringing git-parse-remote back).

1. https://lore.kernel.org/git/cover-v3-0.4-00000000000-20210911T111435Z-avarab@gmail.com/
2. https://lore.kernel.org/git/87tuiwjfvi.fsf@evledraar.gmail.com/