From: Jeff King <peff@peff.net>
Date: Tue, 31 Oct 2023 19:09:59 GMT
Subject: Re: [bug] 2.39.0: error in help for ls-remote
Message-ID: <20231031190959.GA875658@coredump.intra.peff.net>
In-Reply-To: <CAOh4nmm9fTm8fa=1Hyi8t3R-VMnf30-0xe0vcst57dvY-FrL+w@mail.gmail.com>

On Tue, Oct 31, 2023 at 02:11:23PM -0400, Jeremy Hetzler wrote:

> The short help for ls-remote advertises that '-h' is short for '--heads':
> [...]
> However, 'git ls-remote -h' instead prints the help. So perhaps the
> help message should be revised.

It does work as documented with an argument, like:

  git ls-remote -h <remote>

Yes, this is somewhat weird, but is a balance between consistency and
backwards compatibility. See:

  https://lore.kernel.org/git/YU4QxcORBBR01iV8@coredump.intra.peff.net/

as a starting point for past discussions.

The manpage (or "--help") describes the behavior correctly; it may be
that the "-h" output could do so as well, but it's sometimes hard to
communicate such subtleties in such a terse format. So there may be room
for a patch to make things more clear there, but I think it may be
difficult to do well.

-Peff