* [PATCH 1/1] ls-remote: don't use '-h' for options
@ 2020-02-27 11:42 dev
2020-02-27 13:08 ` Danh Doan
0 siblings, 1 reply; 6+ messages in thread
From: dev @ 2020-02-27 11:42 UTC (permalink / raw)
To: git
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(-)
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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] ls-remote: don't use '-h' for options
2020-02-27 11:42 [PATCH 1/1] ls-remote: don't use '-h' for options dev
@ 2020-02-27 13:08 ` Danh Doan
2020-02-27 14:10 ` Pascal Roeleven
0 siblings, 1 reply; 6+ messages in thread
From: Danh Doan @ 2020-02-27 13:08 UTC (permalink / raw)
To: dev; +Cc: git
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
>
> 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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] ls-remote: don't use '-h' for options
2020-02-27 13:08 ` Danh Doan
@ 2020-02-27 14:10 ` Pascal Roeleven
2020-02-27 16:10 ` Junio C Hamano
0 siblings, 1 reply; 6+ messages in thread
From: Pascal Roeleven @ 2020-02-27 14:10 UTC (permalink / raw)
To: Danh Doan; +Cc: git
On 2020-02-27 14:08, Danh Doan wrote:
> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] ls-remote: don't use '-h' for options
2020-02-27 14:10 ` Pascal Roeleven
@ 2020-02-27 16:10 ` Junio C Hamano
2020-02-27 17:39 ` Pascal Roeleven
0 siblings, 1 reply; 6+ messages in thread
From: Junio C Hamano @ 2020-02-27 16:10 UTC (permalink / raw)
To: Pascal Roeleven; +Cc: Danh Doan, git
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(-)
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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] ls-remote: don't use '-h' for options
2020-02-27 16:10 ` Junio C Hamano
@ 2020-02-27 17:39 ` Pascal Roeleven
2020-02-27 17:54 ` Junio C Hamano
0 siblings, 1 reply; 6+ messages in thread
From: Pascal Roeleven @ 2020-02-27 17:39 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Danh Doan, git
On 2020-02-27 17:10, Junio C Hamano wrote:
> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] ls-remote: don't use '-h' for options
2020-02-27 17:39 ` Pascal Roeleven
@ 2020-02-27 17:54 ` Junio C Hamano
0 siblings, 0 replies; 6+ messages in thread
From: Junio C Hamano @ 2020-02-27 17:54 UTC (permalink / raw)
To: Pascal Roeleven; +Cc: Danh Doan, git
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.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2020-02-27 17:54 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-02-27 11:42 [PATCH 1/1] ls-remote: don't use '-h' for options dev
2020-02-27 13:08 ` Danh Doan
2020-02-27 14:10 ` Pascal Roeleven
2020-02-27 16:10 ` Junio C Hamano
2020-02-27 17:39 ` Pascal Roeleven
2020-02-27 17:54 ` Junio C Hamano
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).