Bug 1662318

Summary: Doc: man page should say that "git ls-remote -h" returns usage, not heads
Product: [Fedora] Fedora Reporter: Steve <y9t7sypezp>
Component: gitAssignee: Petr Stodulka <pstodulk>
Status: CLOSED UPSTREAM QA Contact: Fedora Extras Quality Assurance <extras-qa>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 28CC: amahdal, besser82, c.david86, chrisw, pstodulk, tmz
Target Milestone: ---Keywords: Documentation
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2019-02-15 06:25:32 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

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.