Bug 1662318 - Doc: man page should say that "git ls-remote -h" returns usage, not heads
Summary: Doc: man page should say that "git ls-remote -h" returns usage, not heads
Keywords:
Status: CLOSED UPSTREAM
Alias: None
Product: Fedora
Classification: Fedora
Component: git
Version: 28
Hardware: Unspecified
OS: Unspecified
unspecified
unspecified
Target Milestone: ---
Assignee: Petr Stodulka
QA Contact: Fedora Extras Quality Assurance
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2018-12-27 16:25 UTC by Steve
Modified: 2019-02-15 06:25 UTC (History)
6 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2019-02-15 06:25:32 UTC


Attachments (Terms of Use)

Description Steve 2018-12-27 16:25:18 UTC
Description of problem:

The "-h" option to "git ls-remote" is an alias for "--heads", except when "-h" is not used with any other options, in which case, a usage string is returned.

That is by design, but the man page does not say so.

$ git ls-remote -h
usage: git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]
...

Compare with:

$ git ls-remote --heads

However:

$ man git-ls-remote
...
       -h, --heads, -t, --tags
           Limit to only refs/heads and refs/tags, respectively. These options are not mutually exclusive; when given both, references stored
           in refs/heads and refs/tags are displayed.
...

Version-Release number of selected component (if applicable):
git-2.17.2-2.fc28.x86_64

How reproducible:
Always.

Steps to Reproduce:
$ man git-ls-remote

Actual results:
The man page says that the "-h" option is an alias for the "--heads" option.

Expected results:
The man page should explain that when the "-h" option is not used with any other options, a usage string is returned.

Additional info:

These behave as expected:

$ git ls-remote -th
$ git ls-remote -ht

$ git ls-remote --heads
$ git ls-remote -t
$ git ls-remote --tags

Related commit:

ls-remote: a lone "-h" is asking for help
https://github.com/git/git/commit/91a640ffb6d9dd10c293a575a692d9771b6e13c7

Comment 1 Todd Zullinger 2018-12-27 20:37:53 UTC
This seems like something perfect for a new contributor to submit upstream.  That process is documented at https://git-scm.com/docs/SubmittingPatches.html.  The file to patch would be Documentation/git-ls-remote.txt.  Any interest in pushing that upstream?

Comment 2 Todd Zullinger 2019-02-15 06:25:32 UTC
Closing due to lack of response.  This should be fixed upstream by someone interested.


Note You need to log in before you can comment on or make changes to this bug.