Subject: Re: Wrong option -h in grep, ls-remote, and show-ref.

From: Junio C Hamano <[email-masked]>
Date: Fri, 24 Sep 2021 11:12:56 -0700

Ignacy Gawedzki <[email-masked]> writes:

> What did you do before the bug happened? (Steps to reproduce your issue)
>
> git ls-remote -h
>
> What did you expect to happen? (Expected behavior)
>
> The same as git ls-remote --heads.
>
> What happened instead? (Actual behavior)
>
> Displayed the git ls-remote usage.

Thanks for a report, but this is very much working as intended.

There may be some subcommands that assign their own meaning to "-h"
for historical reasons (like "ls-remote -h origin"), or for external
reasons (like "grep -h -e pattern"), but most newbies expect a short
help out of "-h" uniformly across subcommands.

Fortunately, "-h" alone would not make any sense for "grep" (you
need a pattern) and you do not need to use "-h" for "ls-remote" [*].
We prioritized to help newbies by consistently giving a short help
across subcommands, over letting "git grep -h" to complain "you need
to give me a pattern", like so:

    $ git ls-remote --heads
    fatal: No remote configured to list refs from.

    $ git grep
    fatal: no pattern given

    $ git grep -h
    usage: git grep [<options>] [-e] <pattern> [<rev>...] [[--] <path>...]

    --cached              search in index instead of in the work tree
    ...

    $ git ls-remote -h
    usage: git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]
                         [-q | --quiet] [--exit-code] [--get-url]
    ...

HTH.

[Footnote]

* It is not end-user facing Porcelain, but is meant for scripting,
  and you can afford to write "--heads".  Besides, "-h" acts as
  "--heads" in "git ls-remote -h origin" or "git ls-remote -h -q"
  just fine.  Only the "-h and nothing else is given" case is
  sacrificed to help newbies in the case of this subcommand.