# [bug] 2.39.0: error in help for ls-remote

3 messages from 2023-10-31 to 2023-10-31. Participants: Jeremy Hetzler, Jeff King.
Thread: https://gitlist.dev/t/60451

## Jeremy Hetzler, 2023-10-31 18:11

Subject: [bug] 2.39.0: error in help for ls-remote
Message-ID: <CAOh4nmm9fTm8fa=1Hyi8t3R-VMnf30-0xe0vcst57dvY-FrL+w@mail.gmail.com>
URL: https://gitlist.dev/e/CAOh4nmm9fTm8fa%3D1Hyi8t3R-VMnf30-0xe0vcst57dvY-FrL%2Bw%40mail.gmail.com
In-Reply-To: <CAOh4nmk2KZBTuW9qn_ZgDY3yLRZ6NgGOWuBMLRRm1sU=pdmRoQ@mail.gmail.com>

```
All,

The short help for ls-remote advertises that '-h' is short for '--heads':

> usage: git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]
>                      [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]
>                      [--symref] [<repository> [<refs>...]]
>
>
>     -q, --quiet           do not print remote URL
>     --upload-pack <exec>  path of git-upload-pack on the remote host
>     -t, --tags            limit to tags
>     -h, --heads           limit to heads
>     --refs                do not show peeled tags
>     --get-url             take url.<base>.insteadOf into account
>     --sort <key>          field name to sort on
>     --exit-code           exit with exit code 2 if no matching refs are found
>     --symref              show underlying ref in addition to the object pointed by it
>     -o, --server-option <server-specific>
>                           option to transmit

However, 'git ls-remote -h' instead prints the help. So perhaps the
help message should be revised.

git version 2.39.0

Thanks,
Jeremy

```

## Jeff King, 2023-10-31 19:09

Subject: Re: [bug] 2.39.0: error in help for ls-remote
Message-ID: <20231031190959.GA875658@coredump.intra.peff.net>
URL: https://gitlist.dev/e/20231031190959.GA875658%40coredump.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

```

## Jeremy Hetzler, 2023-10-31 23:06

Subject: Re: [bug] 2.39.0: error in help for ls-remote
Message-ID: <CAOh4nmmxjS177FhdvaEfqkomxe3Q51AbDQrn0RGz+7GXiqaMFA@mail.gmail.com>
URL: https://gitlist.dev/e/CAOh4nmmxjS177FhdvaEfqkomxe3Q51AbDQrn0RGz%2B7GXiqaMFA%40mail.gmail.com
In-Reply-To: <20231031190959.GA875658@coredump.intra.peff.net>

```
On Tue, Oct 31, 2023 at 3:10 PM Jeff King <peff@peff.net> wrote:
>
> 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

I see.

I would still find it clearer if there were a fuller explanation in
the "-h" output, but it's not a big deal. At least I'm not the only
one who's been confused :)

Thanks,
Jeremy

```