{"thread":{"id":"52899","subject":"[PATCH 1/1] ls-remote: don't use '-h' for options","startedAt":"2020-02-27T12:48:31Z","lastAt":"2020-02-27T17:54:14Z","messageCount":6,"participants":["dev@pascalroeleven.nl","Danh Doan","Pascal Roeleven","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":1},"messages":[{"id":"392606","messageId":"b0397b3285eab3448a3fd5dd2c50abb9@pascalroeleven.nl","threadId":"52899","inReplyTo":null,"subject":"[PATCH 1/1] ls-remote: don't use '-h' for options","fromName":"","fromEmail":"dev@pascalroeleven.nl","sentAt":"2020-02-27T11:42:18Z","receivedAt":"2020-02-27T12:48:31Z","isPatch":true,"sender":{"key":"dev@pascalroeleven.nl","avatar":null},"body":"The '-h' option for ls-remote will never be reached as the argument is\nalready processed by the git wrapper before passed on to ls-remote.\nThe ls-remote help text will therefore be displayed instead of the\n'--heads' option.\n\nSigned-off-by: Pascal Roeleven \n---\n Documentation/git-ls-remote.txt | 1 -\n builtin/ls-remote.c | 2 +-\n 2 files changed, 1 insertion(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-ls-remote.txt \nb/Documentation/git-ls-remote.txt\nindex a2ea1fd..b5b7d7a 100644\n--- a/Documentation/git-ls-remote.txt\n+++ b/Documentation/git-ls-remote.txt\n@@ -21,7 +21,6 @@ commit IDs.\n\n OPTIONS\n -------\n--h::\n --heads::\n -t::\n --tags::\ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex 6ef5195..85ce336 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -63,7 +63,7 @@ int cmd_ls_remote(int argc, const char **argv, const \nchar *prefix)\n \t\t\t N_(\"path of git-upload-pack on the remote host\"),\n \t\t\t PARSE_OPT_HIDDEN },\n \t\tOPT_BIT('t', \"tags\", &flags, N_(\"limit to tags\"), REF_TAGS),\n-\t\tOPT_BIT('h', \"heads\", &flags, N_(\"limit to heads\"), REF_HEADS),\n+\t\tOPT_BIT(0, \"heads\", &flags, N_(\"limit to heads\"), REF_HEADS),\n \t\tOPT_BIT(0, \"refs\", &flags, N_(\"do not show peeled tags\"), \nREF_NORMAL),\n \t\tOPT_BOOL(0, \"get-url\", &get_url,\n \t\t\t N_(\"take url..insteadOf into account\")),\n-- \n2.20.1\n\n"},{"id":"392608","messageId":"20200227130833.GA10339@danh.dev","threadId":"52899","inReplyTo":"b0397b3285eab3448a3fd5dd2c50abb9@pascalroeleven.nl","subject":"Re: [PATCH 1/1] ls-remote: don't use '-h' for options","fromName":"Danh Doan","fromEmail":"congdanhqx@gmail.com","sentAt":"2020-02-27T13:08:33Z","receivedAt":"2020-02-27T13:08:40Z","isPatch":true,"sender":{"key":"congdanhqx@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42673067?v=4"},"body":"On 2020-02-27 12:42:18+0100, dev@pascalroeleven.nl wrote:\n> The '-h' option for ls-remote will never be reached as the argument is\n> already processed by the git wrapper before passed on to ls-remote.\n> The ls-remote help text will therefore be displayed instead of the\n> '--heads' option.\n\nNo, git ls-remote still see '-h'\n\n- 'git ls-remote -h' will show short help.\n- 'git ls-remote -h ' and 'git ls-remote --heads '\n will show the same output\n\nSee also:\nhttps://lore.kernel.org/git/xmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com/\n\nxmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com\n\n> \n> Signed-off-by: Pascal Roeleven \n> ---\n> Documentation/git-ls-remote.txt | 1 -\n> builtin/ls-remote.c | 2 +-\n> 2 files changed, 1 insertion(+), 2 deletions(-)\n> \n> diff --git a/Documentation/git-ls-remote.txt\n> b/Documentation/git-ls-remote.txt\n> index a2ea1fd..b5b7d7a 100644\n> --- a/Documentation/git-ls-remote.txt\n> +++ b/Documentation/git-ls-remote.txt\n> @@ -21,7 +21,6 @@ commit IDs.\n> \n> OPTIONS\n> -------\n> --h::\n> --heads::\n> -t::\n> --tags::\n> diff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\n> index 6ef5195..85ce336 100644\n> --- a/builtin/ls-remote.c\n> +++ b/builtin/ls-remote.c\n> @@ -63,7 +63,7 @@ int cmd_ls_remote(int argc, const char **argv, const char\n> *prefix)\n> \t\t\t N_(\"path of git-upload-pack on the remote host\"),\n> \t\t\t PARSE_OPT_HIDDEN },\n> \t\tOPT_BIT('t', \"tags\", &flags, N_(\"limit to tags\"), REF_TAGS),\n> -\t\tOPT_BIT('h', \"heads\", &flags, N_(\"limit to heads\"), REF_HEADS),\n> +\t\tOPT_BIT(0, \"heads\", &flags, N_(\"limit to heads\"), REF_HEADS),\n> \t\tOPT_BIT(0, \"refs\", &flags, N_(\"do not show peeled tags\"), REF_NORMAL),\n> \t\tOPT_BOOL(0, \"get-url\", &get_url,\n> \t\t\t N_(\"take url..insteadOf into account\")),\n> -- \n> 2.20.1\n> \n\n-- \nDanh\n"},{"id":"392614","messageId":"03985e4099e82f04709d5ea9ca2a56a6@pascalroeleven.nl","threadId":"52899","inReplyTo":"20200227130833.GA10339@danh.dev","subject":"Re: [PATCH 1/1] ls-remote: don't use '-h' for options","fromName":"Pascal Roeleven","fromEmail":"dev@pascalroeleven.nl","sentAt":"2020-02-27T14:10:17Z","receivedAt":"2020-02-27T14:10:21Z","isPatch":true,"sender":{"key":"dev@pascalroeleven.nl","avatar":null},"body":"On 2020-02-27 14:08, Danh Doan wrote:\n> On 2020-02-27 12:42:18+0100, dev@pascalroeleven.nl wrote:\n>> The '-h' option for ls-remote will never be reached as the argument is\n>> already processed by the git wrapper before passed on to ls-remote.\n>> The ls-remote help text will therefore be displayed instead of the\n>> '--heads' option.\n> \n> No, git ls-remote still see '-h'\n> \n> - 'git ls-remote -h' will show short help.\n> - 'git ls-remote -h ' and 'git ls-remote --heads '\n> will show the same output\n> \n> See also:\n> https://lore.kernel.org/git/xmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com/\n> \n> xmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com\n\nYou are right, I didn't test with . Thanks for pointing me to \nthe old discussion.\n\nBecause '--heads' can be used without a remote, and '-h' is advertised \nas the shorthand equivalent, they should produce exactly the same \noutput. And they don't. The discussion aside if you should use '-h' for \nanything at all except showing help, in my opinion if an option is \nlisted as an alias for another option, they should produce the same \nresult for all (or in this case the lack of) parameters.\n\nIn my case I looked into the documentation, used '-h' exactly as \ndescribed ('' is optional) and it didn't produce the output as \ndescribed. If you ask me, either the code or the documentation should be \nchanged.\n"},{"id":"392624","messageId":"xmqqa754gger.fsf@gitster-ct.c.googlers.com","threadId":"52899","inReplyTo":"03985e4099e82f04709d5ea9ca2a56a6@pascalroeleven.nl","subject":"Re: [PATCH 1/1] ls-remote: don't use '-h' for options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-02-27T16:10:20Z","receivedAt":"2020-02-27T16:10:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pascal Roeleven writes:\n\n> In my case I looked into the documentation, used '-h' exactly as\n> described ('' is optional) and it didn't produce the output as\n> described. If you ask me, either the code or the documentation should\n> be changed.\n\nYeah, I tend to agree that documentation could be better. \n\nYou may think that nobody would ask your opinion, but proposing a\nchange by sending a patch often makes you heard around here ;-)\n\nThanks.\n\n-- >8 --\nSubject: [PATCH] Documentation: clarify that `-h` alone stands for `help`\n\nWe seem to be getting new users who get confused every 20 months or\nso with this \"-h consistently wants to give help, but the commands\nto which `-h` may feel like a good short-form option want it to mean\nsomething else.\" compromise.\n\nLet's make sure that the readers know that `git cmd -h` (with no\nother arguments) is a way to get usage text, even for commands like\nls-remote and grep.\n\nAlso extend the description that is already in gitcli.txt, as it is\nclear that users still get confused with the current text.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-ls-remote.txt | 4 +++-\n Documentation/gitcli.txt | 5 +++++\n 2 files changed, 8 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\nindex a2ea1fd687..0a5c8b7d49 100644\n--- a/Documentation/git-ls-remote.txt\n+++ b/Documentation/git-ls-remote.txt\n@@ -28,7 +28,9 @@ OPTIONS\n \tLimit to only refs/heads and refs/tags, respectively.\n \tThese options are _not_ mutually exclusive; when given\n \tboth, references stored in refs/heads and refs/tags are\n-\tdisplayed.\n+\tdisplayed. Note that `git ls-remote -h` used without\n+\tanything else on the command line gives help, consistent\n+\twith other git subcommands.\n \n --refs::\n \tDo not show peeled tags or pseudorefs like `HEAD` in the output.\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex 373cfa2264..92e4ba6a2f 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -126,6 +126,11 @@ usage: git describe [] *\n --long always use long format\n --abbrev[=] use digits to display SHA-1s\n ---------------------------------------------\n++\n+Note that some subcommand (e.g. `git grep`) may behave differently\n+when there are things on the command line other than `-h`, but `git\n+subcmd -h` without anything else on the command line is meant to\n+consistently give the usage.\n \n --help-all::\n \tSome Git commands take options that are only used for plumbing or that\n"},{"id":"392631","messageId":"74969200f4dd2993eece8308a72546c3@pascalroeleven.nl","threadId":"52899","inReplyTo":"xmqqa754gger.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH 1/1] ls-remote: don't use '-h' for options","fromName":"Pascal Roeleven","fromEmail":"dev@pascalroeleven.nl","sentAt":"2020-02-27T17:39:44Z","receivedAt":"2020-02-27T17:39:51Z","isPatch":true,"sender":{"key":"dev@pascalroeleven.nl","avatar":null},"body":"On 2020-02-27 17:10, Junio C Hamano wrote:\n> Yeah, I tend to agree that documentation could be better.\n> \n> You may think that nobody would ask your opinion, but proposing a\n> change by sending a patch often makes you heard around here ;-)\n> \n> Thanks.\n\nWell, that's good to know :)\n\n> Subject: [PATCH] Documentation: clarify that `-h` alone stands for \n> `help`\n\nAlthough I still don't quite agree with the inner workings of this \ncommand (but I understand the choice because of \nbackwards-compatibility), this extra documentation will definitely \neliminate confusion.\n"},{"id":"392632","messageId":"xmqqk147gblq.fsf@gitster-ct.c.googlers.com","threadId":"52899","inReplyTo":"74969200f4dd2993eece8308a72546c3@pascalroeleven.nl","subject":"Re: [PATCH 1/1] ls-remote: don't use '-h' for options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-02-27T17:54:09Z","receivedAt":"2020-02-27T17:54:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pascal Roeleven writes:\n\n> Although I still don't quite agree with the inner workings of this\n> command (but I understand the choice because of\n> backwards-compatibility),...\n\nYeah, the unpleasant backstory is that \"ls-remote -h\" predates the\nuniversal \"-h\" support offered by the parse-options API by a large\nmargin.\n\n"}]}