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

Ævar Arnfjörð Bjarmason  [off-list ref] writes:

Isn't this, and a lot more importantly the next one ...

... 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.

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

Ævar Arnfjörð Bjarmason  [off-list ref] writes:

quoted

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 ...

quoted

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/