Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 17, 2017, 23:22 UTC
Message-ID: <xmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <774f08bd-3172-0083-1544-e5f68f6798fa@web.de>

René Scharfe <l.s.r@web.de> writes:

Show 10 quoted lines

> Stop advertising -h as the short equivalent of --heads, because it's
> used for showing a short help text for almost all other git commands.
> Since the ba5f28bf79 (ls-remote: use parse-options api) it has only
> been working when used together with other parameters anyway.
>
> Signed-off-by: Rene Scharfe <l.s.r@web.de>
> ---
> That would be step on the way towards more consistent command line
> switches, in the same vein as d69155119 (t0012: test "-h" with
> builtins).

Sorry, but I am not sure whom this and the other approach are trying to help.

The rule we have currently seems to be that "git cmd -h" (no other arguments) consistently gives a short help, and if a subcommand supports an option "-h" specific to it that is not about giving a short help, the caller needs to be aware of it to invoke the option, by making sure that there is some other arguments on the command line if "-h" form of that subcommand specific option is used, by doing e.g. "git ls-remote -h origin" or "git ls-remote --head".

I can see that this "alternative" approach makes it less convenent for folks who have followed that rule by hiding "-h" (with the intention of deprecating and possibly removing it in the future) and encouraging (and later foring) "--head" to be used instead.

The other approach burdens new users by changing the rule to "some subcommands that have their own '-h' option cannot be asked for a brief usage with 'git cmd -h'". But the thing is, these new users who do not know which subcommands do have their own '-h' and which ones do not are the ones that benefit most from the consistent "'git cmd -h' with no other argument gets short help" rule.

When making a backward incompatible change, it is asking us to go to those who are inconvenienced and say "I am sorry that we are making things less convenient for you, but by doing so we can gain this greater good which is ...". I can explain how this and the other approach make things less convenient for existing or new users, but I am having a hard time formulating what the greater good is.

In short, I cannot sell this change to our users. Please help me do so if you want this (or the other) change made to our system.