threads / patch / 52899

patchls-remote: don't use '-h' for options

Subject: [PATCH 1/1] ls-remote: don't use '-h' for options

## tl;dr

6 messages between Feb 27, 2020 and Feb 27, 2020. Diffs are folded; open one to read it.

replies: 5people: 3as markdown or json

dev@pascalroeleven.nl· Feb 27, 2020, 11:42 UTC · lore

The '-h' option for ls-remote will never be reached as the argument is already processed by the git wrapper before passed on to ls-remote. The ls-remote help text will therefore be displayed instead of the '--heads' option.

Signed-off-by: Pascal Roeleven <dev@pascalroeleven.nl>
---
  Documentation/git-ls-remote.txt | 1 -
  builtin/ls-remote.c             | 2 +-
  2 files changed, 1 insertion(+), 2 deletions(-)
Show changes to 2 files +1 −2

Documentation/git-ls-remote.txt, builtin/ls-remote.c

diff --git a/Documentation/git-ls-remote.txt 
b/Documentation/git-ls-remote.txt
index a2ea1fd..b5b7d7a 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -21,7 +21,6 @@ commit IDs.

  OPTIONS
  -------
--h::
  --heads::
  -t::
  --tags::
diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
index 6ef5195..85ce336 100644
--- a/builtin/ls-remote.c
+++ b/builtin/ls-remote.c
@@ -63,7 +63,7 @@ int cmd_ls_remote(int argc, const char **argv, const 
char *prefix)
  			   N_("path of git-upload-pack on the remote host"),
  			   PARSE_OPT_HIDDEN },
  		OPT_BIT('t', "tags", &flags, N_("limit to tags"), REF_TAGS),
-		OPT_BIT('h', "heads", &flags, N_("limit to heads"), REF_HEADS),
+		OPT_BIT(0, "heads", &flags, N_("limit to heads"), REF_HEADS),
  		OPT_BIT(0, "refs", &flags, N_("do not show peeled tags"), 
REF_NORMAL),
  		OPT_BOOL(0, "get-url", &get_url,
  			 N_("take url.<base>.insteadOf into account")),

-- 
2.20.1
Danh Doan· Feb 27, 2020, 13:08 UTC · re: dev@pascalroeleven.nl · lore

Re: [PATCH 1/1] ls-remote: don't use '-h' for options

On 2020-02-27 12:42:18+0100, dev@pascalroeleven.nl wrote:
> The '-h' option for ls-remote will never be reached as the argument is
> already processed by the git wrapper before passed on to ls-remote.
> The ls-remote help text will therefore be displayed instead of the
> '--heads' option.
No, git ls-remote still see '-h'
- 'git ls-remote -h' will show short help.
- 'git ls-remote -h <remote>' and 'git ls-remote --heads <remote>'
  will show the same output

See also: https://lore.kernel.org/git/xmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com/

xmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com
Show 37 quoted lines
> 
> Signed-off-by: Pascal Roeleven <dev@pascalroeleven.nl>
> ---
>  Documentation/git-ls-remote.txt | 1 -
>  builtin/ls-remote.c             | 2 +-
>  2 files changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-ls-remote.txt
> b/Documentation/git-ls-remote.txt
> index a2ea1fd..b5b7d7a 100644
> --- a/Documentation/git-ls-remote.txt
> +++ b/Documentation/git-ls-remote.txt
> @@ -21,7 +21,6 @@ commit IDs.
> 
>  OPTIONS
>  -------
> --h::
>  --heads::
>  -t::
>  --tags::
> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c
> index 6ef5195..85ce336 100644
> --- a/builtin/ls-remote.c
> +++ b/builtin/ls-remote.c
> @@ -63,7 +63,7 @@ int cmd_ls_remote(int argc, const char **argv, const char
> *prefix)
>  			   N_("path of git-upload-pack on the remote host"),
>  			   PARSE_OPT_HIDDEN },
>  		OPT_BIT('t', "tags", &flags, N_("limit to tags"), REF_TAGS),
> -		OPT_BIT('h', "heads", &flags, N_("limit to heads"), REF_HEADS),
> +		OPT_BIT(0, "heads", &flags, N_("limit to heads"), REF_HEADS),
>  		OPT_BIT(0, "refs", &flags, N_("do not show peeled tags"), REF_NORMAL),
>  		OPT_BOOL(0, "get-url", &get_url,
>  			 N_("take url.<base>.insteadOf into account")),
> -- 
> 2.20.1
> 
-- 
Danh
Pascal Roeleven· Feb 27, 2020, 14:10 UTC · re: Danh Doan · lore

Re: [PATCH 1/1] ls-remote: don't use '-h' for options

On 2020-02-27 14:08, Danh Doan wrote:
Show 16 quoted lines
> On 2020-02-27 12:42:18+0100, dev@pascalroeleven.nl wrote:
>> The '-h' option for ls-remote will never be reached as the argument is
>> already processed by the git wrapper before passed on to ls-remote.
>> The ls-remote help text will therefore be displayed instead of the
>> '--heads' option.
> 
> No, git ls-remote still see '-h'
> 
> - 'git ls-remote -h' will show short help.
> - 'git ls-remote -h <remote>' and 'git ls-remote --heads <remote>'
>   will show the same output
> 
> See also:
> https://lore.kernel.org/git/xmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com/
> 
> xmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com

You are right, I didn't test with <remote>. Thanks for pointing me to the old discussion.

Because '--heads' can be used without a remote, and '-h' is advertised as the shorthand equivalent, they should produce exactly the same output. And they don't. The discussion aside if you should use '-h' for anything at all except showing help, in my opinion if an option is listed as an alias for another option, they should produce the same result for all (or in this case the lack of) parameters.

In my case I looked into the documentation, used '-h' exactly as described ('<refs>' is optional) and it didn't produce the output as described. If you ask me, either the code or the documentation should be changed.

Junio C Hamano· Feb 27, 2020, 16:10 UTC · re: Pascal Roeleven · lore

Re: [PATCH 1/1] ls-remote: don't use '-h' for options

Pascal Roeleven <dev@pascalroeleven.nl> writes:
> In my case I looked into the documentation, used '-h' exactly as
> described ('<refs>' is optional) and it didn't produce the output as
> described. If you ask me, either the code or the documentation should
> be changed.
Yeah, I tend to agree that documentation could be better.

You may think that nobody would ask your opinion, but proposing a change by sending a patch often makes you heard around here ;-)

Thanks.
-- >8 --
Subject: [PATCH] Documentation: clarify that `-h` alone stands for `help`

We seem to be getting new users who get confused every 20 months or so with this "-h consistently wants to give help, but the commands to which `-h` may feel like a good short-form option want it to mean something else." compromise.

Let's make sure that the readers know that `git cmd -h` (with no other arguments) is a way to get usage text, even for commands like ls-remote and grep.

Also extend the description that is already in gitcli.txt, as it is clear that users still get confused with the current text.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-ls-remote.txt | 4 +++-
 Documentation/gitcli.txt        | 5 +++++
 2 files changed, 8 insertions(+), 1 deletion(-)
Show changes to 2 files +8 −1

Documentation/git-ls-remote.txt, Documentation/gitcli.txt

diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index a2ea1fd687..0a5c8b7d49 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -28,7 +28,9 @@ OPTIONS
 	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.
+	displayed.  Note that `git ls-remote -h` used without
+	anything else on the command line gives help, consistent
+	with other git subcommands.
 
 --refs::
 	Do not show peeled tags or pseudorefs like `HEAD` in the output.
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 373cfa2264..92e4ba6a2f 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -126,6 +126,11 @@ usage: git describe [<options>] <commit-ish>*
     --long                always use long format
     --abbrev[=<n>]        use <n> digits to display SHA-1s
 ---------------------------------------------
++
+Note that some subcommand (e.g. `git grep`) may behave differently
+when there are things on the command line other than `-h`, but `git
+subcmd -h` without anything else on the command line is meant to
+consistently give the usage.
 
 --help-all::
 	Some Git commands take options that are only used for plumbing or that
Pascal Roeleven· Feb 27, 2020, 17:39 UTC · re: Junio C Hamano · lore

Re: [PATCH 1/1] ls-remote: don't use '-h' for options

On 2020-02-27 17:10, Junio C Hamano wrote:
Show 6 quoted lines
> Yeah, I tend to agree that documentation could be better.
> 
> You may think that nobody would ask your opinion, but proposing a
> change by sending a patch often makes you heard around here ;-)
> 
> Thanks.
Well, that's good to know :)
> Subject: [PATCH] Documentation: clarify that `-h` alone stands for 
> `help`

Although I still don't quite agree with the inner workings of this command (but I understand the choice because of backwards-compatibility), this extra documentation will definitely eliminate confusion.

Junio C Hamano· Feb 27, 2020, 17:54 UTC · re: Pascal Roeleven · lore

Re: [PATCH 1/1] ls-remote: don't use '-h' for options

Pascal Roeleven <dev@pascalroeleven.nl> writes:
> Although I still don't quite agree with the inner workings of this
> command (but I understand the choice because of
> backwards-compatibility),...

Yeah, the unpleasant backstory is that "ls-remote -h" predates the universal "-h" support offered by the parse-options API by a large margin.

← back to recent threads