| Message ID | b0397b3285eab3448a3fd5dd2c50abb9@pascalroeleven.nl (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [1/1] ls-remote: don't use '-h' for options | expand |
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 >
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.
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
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.
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.
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),
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(-) OPT_BOOL(0, "get-url", &get_url, N_("take url.<base>.insteadOf into account")),