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

From: Junio C Hamano <gitster@pobox.com>
Date: May 30, 2024, 03:23 UTC
Message-ID: <xmqq34q0rnio.fsf@gitster.g>
In-Reply-To: <0F971F6E-6462-4E0D-880B-8FD67F42A782@dragondata.com>

Kevin Day <toasty@dragondata.com> writes:

Show 13 quoted lines

>>> 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.
>
> Sorry, let me rephrase that.  1) Apply the fix I was proposing to make
> it so that the command's -h usage has precedence over showing the
> usage. Any tests that break because of that which don't have a
> plausible fix mark as "# TODO known breakage" like several other
> commands have because they aren't generating usage output correctly
> for one reason or another.

Ah, then no.

I am afraid that it is a non starter. "git ls-remote -h" would then stop breaking existing users' long established expectation, i.e., "for any git subcommand 'cmd', you can say 'git cmd -h' to get the short help". We need to design a good transition plan to wean existing users off of that expectation.

For example, we _could_ introduce "-?" to parse-options _now_, and mark the use of "-h" as deprecated. When the special casing of "-h" parse-options has triggers, the user will be reminded that the "-h" support will have a limited shelf life, and they are urged to retrain their fingers and update their scripts to use "-?", possibly with "advice.shorthelpdeprecationnotice" configuration knob that helps ease the transition. We would update the t/ scripts to use "-?" at the same time, but would probably need to keep tests that use "-h" to ensure that the warning triggers.

We will keep things that way for a while, and once we get the users' expectation updated so that they think 'git cmd -?' (not 'git cmd -h') is _the_ way to get the short help for any git subcommand.

At a major version boundary, e.g., Git 3.0, we could remove the special casing of '-h' from parse-options, and "git ls-remote -h" will start working the same way as "git ls-remote -h origin" all of a sudden, but nobody remembers "git ls-remote -h" used to be the way to get short help for the command any more by that time, so nobody will get hurt by such a flipping of the behaviour.