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

[Junio C Hamano <gitster@pobox.com>]

Kevin Day <toasty@dragondata.com> writes:

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