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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 3, 2024, 18:33 UTC
Message-ID: <xmqq8qzl3mhg.fsf@gitster.g>
In-Reply-To: <xmqq34q0rnio.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

Show 7 quoted lines

> Ah, then no.
>
> I am afraid that it is a non starter.  "git ls-remote -h" would then
> start 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.

Another thing I forgot to mention. For "ls-remote" and "show-ref", there is a much nicer transition path we can take. Back in Linus's days, we called branches "heads" (and we used $GIT_DIR/refs/heads/ to store them as individual files), but if we were starting Git from scratch today, there is no reason to. Call branches branches, not heads, which means we do not need to use "-h" to mean "I want to see only the branches and no other refs" at all. You say "--branches" instead.

Which leads to an obvious transition path, which is

 * Introduce "--branches" that sits next to "--tags" to "ls-remote"
   and "show-ref".  If the command has "-t" as a short-hand for
   "--tags", then add "-b" as a short-hand for "--branches".
   Announce that "--heads" (and "-h" if supported) is deprecated for
   these commands, and when "--heads" (and "-h" if supported) is
   used, give a warning to train finger/muscle memory early.

 * We will keep things that way for a while, and then remove the
   "--heads" (and "-h" if supported) from these two commands.

The approach cannot be used to transition "git grep -h" for obvious reasons, but then it makes no sense to give "-h" alone to tell the command "I do not want to see filenames", so that is not a problem.

I checked output from

    $ git grep -A2 '^-h' Documentation/

and it seems that ls-remote is the only one that matters, so we do not even have to do the "-?" transition at all.

Thanks.