Re: Commands using -h as an option don't work consistently

From: Junio C Hamano <gitster@pobox.com>
Date: May 29, 2024, 22:22 UTC
Message-ID: <xmqqfru0tg1a.fsf@gitster.g>
In-Reply-To: <52819526-4C6F-418C-8B8B-A4D5C7E371EA@dragondata.com>

Kevin Day <toasty@dragondata.com> writes:

Show 18 quoted lines

> Because of a bug in parse-options.c, any command that has a '-h' option will sometimes display the usage page instead of executing. For example, ls-remote has two options:
>
>     -t, --[no-]tags       limit to tags
>     -h, --[no-]heads      limit to heads
>
> git ls-remote --heads  #works
> git ls-remote --tags  #works
> git ls-remote -t  #works
> git ls-remote -t -h  #works
> git ls-remote -h  #shows the help page
>
> This is because of these lines in parse-options.c:
>
> /* lone -h asks for help */
> if (internal_help && ctx->total == 1 && !strcmp(arg + 1, "h"))
> goto show_usage;
>
> This is being executed before it looks to see if there actually is a -h option.

This is very much deliberate design. I think in these cases we make an unambiguous longhand (e.g. "--heads" we see above) available, or you can explicitly say the remote, i.e. "git ls-remote -h origin", and that has been the officially accepted "solution".

Let's see what improvements you bring to the table.

> The options I see:
>
> 1) Fix -h handling and add ignores and fixes where possible to the
> failing tests and try to not use -h as an option for anything new.

I do not quite understand the former half, but "try not to use -h for new things" is a very good idea and it is pretty much what we have been doing.

    Note: There however is a scenario where we cannot avoid it---if
    we were trying to match/mimick some established external
    command, we may have to use the same "-h" as they use (e.g.,
    "git grep -h -e ..." tries to mimick "grep -h -e ...").  Even in
    that case, because "git grep -h" alone would not make any sense
    without any pattern, the command behaves very sensibly, by the
    way.

> 2) Change -h to -H or something, but this breaks backwards compatibility

As you said it yourself, this is a non starter.

Show 5 quoted lines

> 3) Fix it so that -h works if a command uses it, and additionally
> make a new global option -? or --usage or something that always
> shows the usage page and change tests to use that, while leaving
> -h sometimes showing usage and sometimes executing the option to
> preserve as much backward compatibility as possible.

Reading this and then going back to the ls-remote examples you gave earlier, I do not think the current behaviour is all that bad, relative to what is being proposed, except for an explicit support for "-?".

We can certainly add support for "-?", but the behaviour when "-?" is not used (and when "-h" is used) would not have to change from the current behaviour, and that would still be serviceable, I presume?

We actually do not have to *add* support for "-?", as it comes with parse-options for free ;-)

    $ git ls-remote -\?
    error: unknown switch '?'
    usage: git ls-remote ...
	... the same "ls-remote -h" output given here ...

So, I dunno.