{"thread":{"id":"46970","subject":"Bug: git ls-remote -h / --head results differ in output","startedAt":"2017-10-15T10:02:50Z","lastAt":"2017-10-24T18:26:58Z","messageCount":23,"participants":["Thomas Rikl","Martin Ågren","René Scharfe","Jonathan Nieder","Junio C Hamano","Jeff King"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"330396","messageId":"63fe2a84-d991-9165-32c0-8087d8513ce6@online.de","threadId":"46970","inReplyTo":null,"subject":"Bug: git ls-remote -h / --head results differ in output","fromName":"Thomas Rikl","fromEmail":"trikl@online.de","sentAt":"2017-10-15T10:02:42Z","receivedAt":"2017-10-15T10:02:50Z","isPatch":false,"sender":{"key":"trikl@online.de","avatar":null},"body":"Example:\n\ntom1 ~/emacs/spacemacs/.emacs.d $ export LANG=en_US.utf8\n\ntom1 ~/emacs/spacemacs/.emacs.d $ git ls-remote -h\nusage: git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n                      [-q | --quiet] [--exit-code] [--get-url]\n                      [--symref] [<repository> [<refs>...]]\n\n     -q, --quiet           do not print remote URL\n     --upload-pack <exec>  path of git-upload-pack on the remote host\n     -t, --tags            limit to tags\n     -h, --heads           limit to heads\n     --refs                do not show peeled tags\n     --get-url             take url.<base>.insteadOf into account\n     --exit-code           exit with exit code 2 if no matching refs are \nfound\n     --symref              show underlying ref in addition to the object \npointed by it\n\ntom1 ~/emacs/spacemacs/.emacs.d $ git ls-remote --head\n From https://github.com/syl20bnr/spacemacs\n07014deead544c51fa6a826e91fe2ef05bf04323 refs/heads/develop\n8e1af145480d53e8d32cdff2c83291889903164b refs/heads/master\n2450b7e276634ece07b6b7ec6ca6c287af86caf3 refs/heads/release-0.101\n8dadfc1494544bb152e80c2a436e43bc3713b389 refs/heads/release-0.102\nd993a021847cde2c42865bab6afa8adbb2edda0b refs/heads/release-0.103\n44d4525543b1f2a385142721d0cb16cd3b0be580 refs/heads/release-0.104\n9f9faa404e3dec3e08cc73cf7b5a0439fc309800 refs/heads/release-0.105\n8e1af145480d53e8d32cdff2c83291889903164b refs/heads/release-0.200\ntom1 ~/emacs/spacemacs/.emacs.d $ git --version\ngit version 2.14.2\n\non archlinux: Linux achse 4.13.5-1-ARCH #1 SMP PREEMPT Fri Oct 6 \n09:58:47 CEST 2017 x86_64 GNU/Linux\n\n"},{"id":"330397","messageId":"CAN0heSpPWWdWY4d1wCdRH8TjcmD3kAiSffL0-_9kJWkm5P2EkA@mail.gmail.com","threadId":"46970","inReplyTo":"63fe2a84-d991-9165-32c0-8087d8513ce6@online.de","subject":"Re: Bug: git ls-remote -h / --head results differ in output","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2017-10-15T11:08:22Z","receivedAt":"2017-10-15T11:08:29Z","isPatch":false,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On 15 October 2017 at 12:02, Thomas Rikl <trikl@online.de> wrote:\n> Example:\n>\n> tom1 ~/emacs/spacemacs/.emacs.d $ export LANG=en_US.utf8\n>\n> tom1 ~/emacs/spacemacs/.emacs.d $ git ls-remote -h\n> usage: git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n>                      [-q | --quiet] [--exit-code] [--get-url]\n>                      [--symref] [<repository> [<refs>...]]\n>\n>     -q, --quiet           do not print remote URL\n>     --upload-pack <exec>  path of git-upload-pack on the remote host\n>     -t, --tags            limit to tags\n>     -h, --heads           limit to heads\n>     --refs                do not show peeled tags\n>     --get-url             take url.<base>.insteadOf into account\n>     --exit-code           exit with exit code 2 if no matching refs are\n> found\n>     --symref              show underlying ref in addition to the object\n> pointed by it\n>\n> tom1 ~/emacs/spacemacs/.emacs.d $ git ls-remote --head\n> From https://github.com/syl20bnr/spacemacs\n> 07014deead544c51fa6a826e91fe2ef05bf04323 refs/heads/develop\n> 8e1af145480d53e8d32cdff2c83291889903164b refs/heads/master\n> 2450b7e276634ece07b6b7ec6ca6c287af86caf3 refs/heads/release-0.101\n> 8dadfc1494544bb152e80c2a436e43bc3713b389 refs/heads/release-0.102\n> d993a021847cde2c42865bab6afa8adbb2edda0b refs/heads/release-0.103\n> 44d4525543b1f2a385142721d0cb16cd3b0be580 refs/heads/release-0.104\n> 9f9faa404e3dec3e08cc73cf7b5a0439fc309800 refs/heads/release-0.105\n> 8e1af145480d53e8d32cdff2c83291889903164b refs/heads/release-0.200\n> tom1 ~/emacs/spacemacs/.emacs.d $ git --version\n> git version 2.14.2\n>\n> on archlinux: Linux achse 4.13.5-1-ARCH #1 SMP PREEMPT Fri Oct 6 09:58:47\n> CEST 2017 x86_64 GNU/Linux\n\nThe behavior you observed matches with the documentation in gitcli(7)\nand is arguably correct. A lone \"-h\" prints the help/usage. But I would\nagree that this can be confusing, especially when considering\ngit-ls-remote(1) on its own, without any extra knowledge about what a\nlone -h should do.\n\nSo -h and --heads can only be used interchangeably if you have other\narguments. To see this, you could, e.g., try \"git ls-remote -h -h\".\n\nSome more details. This looks like ba5f28bf7 (ls-remote: use\nparse-options api, 2016-01-19). Before that, \"-h\" was handled internally\nin builtin/ls-files.c. After that it is handled in the general\noptions-parsing machinery. See for example 5ad0d3d52 (parse-options:\nallow -h as a short option, 2015-11-17), which explicitly wants to print\nthe usage-string if \"-h\" is given as the lone argument.\n\nI'm not sure which is the best way forward here, or how many other\ncommands could have similar pitfalls. For example, the \"-h\"-flag of git\ngrep shouldn't be able to cause this problem.\n\nMartin\n"},{"id":"330398","messageId":"4d110305-0826-6fd1-91a5-c1ebd0b1e80b@web.de","threadId":"46970","inReplyTo":"CAN0heSpPWWdWY4d1wCdRH8TjcmD3kAiSffL0-_9kJWkm5P2EkA@mail.gmail.com","subject":"Re: Bug: git ls-remote -h / --head results differ in output","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2017-10-15T13:26:05Z","receivedAt":"2017-10-15T13:26:16Z","isPatch":false,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Am 15.10.2017 um 13:08 schrieb Martin Ågren:\n> On 15 October 2017 at 12:02, Thomas Rikl <trikl@online.de> wrote:\n>> Example:\n>>\n>> tom1 ~/emacs/spacemacs/.emacs.d $ export LANG=en_US.utf8\n>>\n>> tom1 ~/emacs/spacemacs/.emacs.d $ git ls-remote -h\n>> usage: git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]\n>>                       [-q | --quiet] [--exit-code] [--get-url]\n>>                       [--symref] [<repository> [<refs>...]]\n>>\n>>      -q, --quiet           do not print remote URL\n>>      --upload-pack <exec>  path of git-upload-pack on the remote host\n>>      -t, --tags            limit to tags\n>>      -h, --heads           limit to heads\n>>      --refs                do not show peeled tags\n>>      --get-url             take url.<base>.insteadOf into account\n>>      --exit-code           exit with exit code 2 if no matching refs are\n>> found\n>>      --symref              show underlying ref in addition to the object\n>> pointed by it\n>>\n>> tom1 ~/emacs/spacemacs/.emacs.d $ git ls-remote --head\n>>  From https://github.com/syl20bnr/spacemacs\n>> 07014deead544c51fa6a826e91fe2ef05bf04323 refs/heads/develop\n>> 8e1af145480d53e8d32cdff2c83291889903164b refs/heads/master\n>> 2450b7e276634ece07b6b7ec6ca6c287af86caf3 refs/heads/release-0.101\n>> 8dadfc1494544bb152e80c2a436e43bc3713b389 refs/heads/release-0.102\n>> d993a021847cde2c42865bab6afa8adbb2edda0b refs/heads/release-0.103\n>> 44d4525543b1f2a385142721d0cb16cd3b0be580 refs/heads/release-0.104\n>> 9f9faa404e3dec3e08cc73cf7b5a0439fc309800 refs/heads/release-0.105\n>> 8e1af145480d53e8d32cdff2c83291889903164b refs/heads/release-0.200\n>> tom1 ~/emacs/spacemacs/.emacs.d $ git --version\n>> git version 2.14.2\n>>\n>> on archlinux: Linux achse 4.13.5-1-ARCH #1 SMP PREEMPT Fri Oct 6 09:58:47\n>> CEST 2017 x86_64 GNU/Linux\n> \n> The behavior you observed matches with the documentation in gitcli(7)\n> and is arguably correct. A lone \"-h\" prints the help/usage. But I would\n> agree that this can be confusing, especially when considering\n> git-ls-remote(1) on its own, without any extra knowledge about what a\n> lone -h should do.\n> \n> So -h and --heads can only be used interchangeably if you have other\n> arguments. To see this, you could, e.g., try \"git ls-remote -h -h\".\n> \n> Some more details. This looks like ba5f28bf7 (ls-remote: use\n> parse-options api, 2016-01-19). Before that, \"-h\" was handled internally\n> in builtin/ls-files.c. After that it is handled in the general\n> options-parsing machinery. See for example 5ad0d3d52 (parse-options:\n> allow -h as a short option, 2015-11-17), which explicitly wants to print\n> the usage-string if \"-h\" is given as the lone argument.\n> \n> I'm not sure which is the best way forward here, or how many other\n> commands could have similar pitfalls. For example, the \"-h\"-flag of git\n> grep shouldn't be able to cause this problem.\n\nThe flag PARSE_OPT_NO_INTERNAL_HELP should be used to let git ls-remote\nfully handle -h.\n\nThe same goes for git show-ref, but perhaps it's better to remove its\nhidden option -h by now.\n\nBut stepping back a bit I wonder if the demure internal -h handler (that\nonly speaks up when nothing else is said) is a bit too subtle.\nReverting 5ad0d3d52 would make the need for PARSE_OPT_NO_INTERNAL_HELP\nmore obvious.\n\nRené\n"},{"id":"330544","messageId":"76c3e710-0655-7788-f6f4-af1e59d65edd@web.de","threadId":"46970","inReplyTo":"4d110305-0826-6fd1-91a5-c1ebd0b1e80b@web.de","subject":"[PATCH 1/2] git: add NO_INTERNAL_HELP flag for builtins","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2017-10-17T15:39:03Z","receivedAt":"2017-10-17T15:39:26Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Builtin commands have skipped repo setup when called with just a single\noption -h and thus shown their short help text even outside of\nrepositories since 99caeed05d3 (Let 'git <command> -h' show usage\nwithout a git dir).\n\nAdd the flag NO_INTERNAL_HELP for builtins to opt out of this special\ntreatment and provide a list of commands that are exempt from the\ncorresponding test in t0012.  That allows builtins to handle -h\nthemselves.\n\nSigned-off-by: Rene Scharfe <l.s.r@web.de>\n---\n git.c           | 6 +++++-\n t/t0012-help.sh | 9 ++++++++-\n 2 files changed, 13 insertions(+), 2 deletions(-)\n\ndiff --git a/git.c b/git.c\nindex 9e96dd4090..9d1b8c4716 100644\n--- a/git.c\n+++ b/git.c\n@@ -298,6 +298,7 @@ static int handle_alias(int *argcp, const char ***argv)\n #define NEED_WORK_TREE\t\t(1<<3)\n #define SUPPORT_SUPER_PREFIX\t(1<<4)\n #define DELAY_PAGER_CONFIG\t(1<<5)\n+#define NO_INTERNAL_HELP\t(1<<6)\n \n struct cmd_struct {\n \tconst char *cmd;\n@@ -312,7 +313,10 @@ static int run_builtin(struct cmd_struct *p, int argc, const char **argv)\n \tconst char *prefix;\n \n \tprefix = NULL;\n-\thelp = argc == 2 && !strcmp(argv[1], \"-h\");\n+\tif (p->option & NO_INTERNAL_HELP)\n+\t\thelp = 0;\n+\telse\n+\t\thelp = argc == 2 && !strcmp(argv[1], \"-h\");\n \tif (!help) {\n \t\tif (p->option & RUN_SETUP)\n \t\t\tprefix = setup_git_directory();\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 487b92a5de..74eeead168 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -53,12 +53,19 @@ test_expect_success 'generate builtin list' '\n \tgit --list-builtins >builtins\n '\n \n+cat >no_internal_help <<EOF\n+EOF\n+\n+test_expect_success 'generate list of builtins with internal help' '\n+\tgrep -w -v -f no_internal_help <builtins >builtins_internal_help\n+'\n+\n while read builtin\n do\n \ttest_expect_success \"$builtin can handle -h\" '\n \t\ttest_expect_code 129 git $builtin -h >output 2>&1 &&\n \t\ttest_i18ngrep usage output\n \t'\n-done <builtins\n+done <builtins_internal_help\n \n test_done\n-- \n2.14.2\n"},{"id":"330545","messageId":"774f08bd-3172-0083-1544-e5f68f6798fa@web.de","threadId":"46970","inReplyTo":"4d110305-0826-6fd1-91a5-c1ebd0b1e80b@web.de","subject":"[Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2017-10-17T15:39:14Z","receivedAt":"2017-10-17T15:39:30Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Stop advertising -h as the short equivalent of --heads, because it's\nused for showing a short help text for almost all other git commands.\nSince the ba5f28bf79 (ls-remote: use parse-options api) it has only\nbeen working when used together with other parameters anyway.\n\nSigned-off-by: Rene Scharfe <l.s.r@web.de>\n---\nThat would be step on the way towards more consistent command line\nswitches, in the same vein as d69155119 (t0012: test \"-h\" with\nbuiltins).\n\n Documentation/git-ls-remote.txt | 1 -\n builtin/ls-remote.c             | 4 +++-\n 2 files changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\nindex 5f2628c8f8..898836a111 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 c4be98ab9e..840deedbef 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -56,7 +56,9 @@ int cmd_ls_remote(int argc, const char **argv, const char *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\t{ OPTION_BIT, 'h', NULL, &flags, NULL, N_(\"limit to heads\"),\n+\t\t\tPARSE_OPT_NOARG | PARSE_OPT_HIDDEN, NULL, 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.<base>.insteadOf into account\")),\n-- \n2.14.2\n"},{"id":"330546","messageId":"f66f3fc2-8f51-03f5-c242-cb6d776af585@web.de","threadId":"46970","inReplyTo":"4d110305-0826-6fd1-91a5-c1ebd0b1e80b@web.de","subject":"[PATCH 2/2] ls-remote: use PARSE_OPT_NO_INTERNAL_HELP","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2017-10-17T15:39:09Z","receivedAt":"2017-10-17T15:39:33Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Since ba5f28bf79 (ls-remote: use parse-options api) git ls-remote -h\nwithout any other options has shown the short help text of the command\ninstead of acting as the short equivalent of --heads.  Fix this\nregression by turning off internal handling of -h for repository setup,\nand option parsing, as well as the corresponding test in t0012.\n\nReported-by: Thomas Rikl <trikl@online.de>\nAnalyzed-by: Martin Ågren <martin.agren@gmail.com>\nSigned-off-by: Rene Scharfe <l.s.r@web.de>\n---\n builtin/ls-remote.c  | 1 +\n git.c                | 2 +-\n t/t0012-help.sh      | 1 +\n t/t5512-ls-remote.sh | 6 ++++++\n 4 files changed, 9 insertions(+), 1 deletion(-)\n\ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex c4be98ab9e..5f27d252b4 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -68,6 +68,7 @@ int cmd_ls_remote(int argc, const char **argv, const char *prefix)\n \t};\n \n \targc = parse_options(argc, argv, prefix, options, ls_remote_usage,\n+\t\t\t     PARSE_OPT_NO_INTERNAL_HELP |\n \t\t\t     PARSE_OPT_STOP_AT_NON_OPTION);\n \tdest = argv[0];\n \ndiff --git a/git.c b/git.c\nindex 9d1b8c4716..056a123506 100644\n--- a/git.c\n+++ b/git.c\n@@ -421,7 +421,7 @@ static struct cmd_struct commands[] = {\n \t{ \"interpret-trailers\", cmd_interpret_trailers, RUN_SETUP_GENTLY },\n \t{ \"log\", cmd_log, RUN_SETUP },\n \t{ \"ls-files\", cmd_ls_files, RUN_SETUP },\n-\t{ \"ls-remote\", cmd_ls_remote, RUN_SETUP_GENTLY },\n+\t{ \"ls-remote\", cmd_ls_remote, RUN_SETUP_GENTLY | NO_INTERNAL_HELP },\n \t{ \"ls-tree\", cmd_ls_tree, RUN_SETUP },\n \t{ \"mailinfo\", cmd_mailinfo, RUN_SETUP_GENTLY },\n \t{ \"mailsplit\", cmd_mailsplit },\ndiff --git a/t/t0012-help.sh b/t/t0012-help.sh\nindex 74eeead168..05d8cf9b49 100755\n--- a/t/t0012-help.sh\n+++ b/t/t0012-help.sh\n@@ -54,6 +54,7 @@ test_expect_success 'generate builtin list' '\n '\n \n cat >no_internal_help <<EOF\n+ls-remote\n EOF\n \n test_expect_success 'generate builtin list with internal help' '\ndiff --git a/t/t5512-ls-remote.sh b/t/t5512-ls-remote.sh\nindex 02106c9226..637e9a87f3 100755\n--- a/t/t5512-ls-remote.sh\n+++ b/t/t5512-ls-remote.sh\n@@ -264,4 +264,10 @@ test_expect_success 'ls-remote works outside repository' '\n \tnongit git ls-remote dst.git\n '\n \n+test_expect_success 'ls-remote -h == ls-remote --heads' '\n+\tgit ls-remote -h >short &&\n+\tgit ls-remote --heads >long &&\n+\ttest_cmp long short\n+'\n+\n test_done\n-- \n2.14.2\n"},{"id":"330556","messageId":"20171017173920.hzsvftikaoi4y6zt@aiede.mtv.corp.google.com","threadId":"46970","inReplyTo":"76c3e710-0655-7788-f6f4-af1e59d65edd@web.de","subject":"Re: [PATCH 1/2] git: add NO_INTERNAL_HELP flag for builtins","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-10-17T17:39:20Z","receivedAt":"2017-10-17T17:40:04Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nRené Scharfe wrote:\n\n> Builtin commands have skipped repo setup when called with just a single\n> option -h and thus shown their short help text even outside of\n> repositories since 99caeed05d3 (Let 'git <command> -h' show usage\n> without a git dir).\n>\n> Add the flag NO_INTERNAL_HELP for builtins to opt out of this special\n> treatment and provide a list of commands that are exempt from the\n> corresponding test in t0012.  That allows builtins to handle -h\n> themselves.\n>\n> Signed-off-by: Rene Scharfe <l.s.r@web.de>\n> ---\n>  git.c           | 6 +++++-\n>  t/t0012-help.sh | 9 ++++++++-\n>  2 files changed, 13 insertions(+), 2 deletions(-)\n\nMakes sense.\n\n[...]\n> +++ b/git.c\n[...]\n> @@ -312,7 +313,10 @@ static int run_builtin(struct cmd_struct *p, int argc, const char **argv)\n>  \tconst char *prefix;\n>  \n>  \tprefix = NULL;\n> -\thelp = argc == 2 && !strcmp(argv[1], \"-h\");\n> +\tif (p->option & NO_INTERNAL_HELP)\n> +\t\thelp = 0;\n> +\telse\n> +\t\thelp = argc == 2 && !strcmp(argv[1], \"-h\");\n\noptional: this could be part of the same expression:\n\n\thelp = !(p->option & NO_INTERNAL_HELP) && argc == 2 && ...;\n\n[...]\n> --- a/t/t0012-help.sh\n> +++ b/t/t0012-help.sh\n> @@ -53,12 +53,19 @@ test_expect_success 'generate builtin list' '\n>  \tgit --list-builtins >builtins\n>  '\n>  \n> +cat >no_internal_help <<EOF\n> +EOF\n> +\n> +test_expect_success 'generate list of builtins with internal help' '\n> +\tgrep -w -v -f no_internal_help <builtins >builtins_internal_help\n> +'\n\nHm, I don't see any instances of \"grep -f\" in the testsuite.  Are\nthere portability pitfalls in it I don't know about?  It's in POSIX,\nso it looks pretty safe.\n\nI would have been tempted to use comm, which is already used in\nt6500-gc.sh:\n\n\tcomm -1 -3 no_internal_help builtins >builtins_internal_help\n\nOther nits:\n\n- preparatory 'cat' commands like the above tend to go inside\n  test_expect_success these days\n\n- test that set up for later tests get marked as 'setup' or 'set up'\n\nWith whatever subset of the changes below looks good squashed in,\nReviewed-by: Jonathan Nieder <jrnieder@gmail.com>\n\nThanks.\n\ndiff --git i/git.c w/git.c\nindex 9d1b8c4716..e4b340df7d 100644\n--- i/git.c\n+++ w/git.c\n@@ -313,10 +313,8 @@ static int run_builtin(struct cmd_struct *p, int argc, const char **argv)\n \tconst char *prefix;\n \n \tprefix = NULL;\n-\tif (p->option & NO_INTERNAL_HELP)\n-\t\thelp = 0;\n-\telse\n-\t\thelp = argc == 2 && !strcmp(argv[1], \"-h\");\n+\thelp = !(p->option & NO_INTERNAL_HELP) &&\n+\t\t\targc == 2 && !strcmp(argv[1], \"-h\");\n \tif (!help) {\n \t\tif (p->option & RUN_SETUP)\n \t\t\tprefix = setup_git_directory();\ndiff --git i/t/t0012-help.sh w/t/t0012-help.sh\nindex c5a748837c..73fdfd99ab 100755\n--- i/t/t0012-help.sh\n+++ w/t/t0012-help.sh\n@@ -49,15 +49,11 @@ test_expect_success \"--help does not work for guides\" \"\n \ttest_i18ncmp expect actual\n \"\n \n-test_expect_success 'generate builtin list' '\n-\tgit --list-builtins >builtins\n-'\n-\n-cat >no_internal_help <<EOF\n-EOF\n-\n-test_expect_success 'generate list of builtins with internal help' '\n-\tgrep -w -v -f no_internal_help <builtins >builtins_internal_help\n+test_expect_success 'set up list of builtins with internal help' '\n+\tcat >no_internal_help <<-\\EOF &&\n+\tEOF\n+\tgit --list-builtins >builtins &&\n+\tcomm -1 -3 no_internal_help builtins >builtins_internal_help\n '\n \n while read builtin\n"},{"id":"330557","messageId":"CAN0heSrR5v3JSXiQaqNTzf58G_CAXO-rL4W-GhQzb+OqLjK6QQ@mail.gmail.com","threadId":"46970","inReplyTo":"774f08bd-3172-0083-1544-e5f68f6798fa@web.de","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2017-10-17T17:40:37Z","receivedAt":"2017-10-17T17:40:46Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On 17 October 2017 at 17:39, René Scharfe <l.s.r@web.de> wrote:\n> Stop advertising -h as the short equivalent of --heads, because it's\n> used for showing a short help text for almost all other git commands.\n> Since the ba5f28bf79 (ls-remote: use parse-options api) it has only\n> been working when used together with other parameters anyway.\n>\n> Signed-off-by: Rene Scharfe <l.s.r@web.de>\n> ---\n> That would be step on the way towards more consistent command line\n> switches, in the same vein as d69155119 (t0012: test \"-h\" with\n> builtins).\n\nFWIW, my first inclination would be to go with a patch like this instead\nof the other two (where you introduce an exception so that git ls-remote\n-h does not display the usage). ba5f28bf79 was in 2.8.0. That's 18\nmonths ago. Not an eternity, but still some time ago. Not fixing this\nregression has an obvious downside, but there's also a downside to\nadding the exception.\n\nAs long as a lone -h may give the usage or do something else entirely,\nthen -- put bluntly -- to know whether you can request the usage with\ngit foo -h without risk of messing up your repo, you'll need to look up\nthe usage some other way. At which point you've solved your original\nproblem, without -h.\n\nOf course, we could promise that -h will give the usage or, in case of\nhistorical wart(s), do something harmless. But it seems a bit awkward,\nand might limit the perceived usefulness/safeness or -h.\n\n> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\n> index 5f2628c8f8..898836a111 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\nDo we want to document -h as a deprecated alias, so that people have a\nslightly larger chance of noticing and adapting?\n"},{"id":"330558","messageId":"20171017174241.zph32u74k6bmir7v@aiede.mtv.corp.google.com","threadId":"46970","inReplyTo":"f66f3fc2-8f51-03f5-c242-cb6d776af585@web.de","subject":"Re: [PATCH 2/2] ls-remote: use PARSE_OPT_NO_INTERNAL_HELP","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-10-17T17:42:41Z","receivedAt":"2017-10-17T17:42:48Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"René Scharfe wrote:\n\n> Since ba5f28bf79 (ls-remote: use parse-options api) git ls-remote -h\n> without any other options has shown the short help text of the command\n> instead of acting as the short equivalent of --heads.  Fix this\n> regression by turning off internal handling of -h for repository setup,\n> and option parsing, as well as the corresponding test in t0012.\n>\n> Reported-by: Thomas Rikl <trikl@online.de>\n> Analyzed-by: Martin Ågren <martin.agren@gmail.com>\n> Signed-off-by: Rene Scharfe <l.s.r@web.de>\n> ---\n>  builtin/ls-remote.c  | 1 +\n>  git.c                | 2 +-\n>  t/t0012-help.sh      | 1 +\n>  t/t5512-ls-remote.sh | 6 ++++++\n>  4 files changed, 9 insertions(+), 1 deletion(-)\n\nReviewed-by: Jonathan Nieder <jrnieder@gmail.com>\n\n[...]\n> --- a/git.c\n> +++ b/git.c\n> @@ -421,7 +421,7 @@ static struct cmd_struct commands[] = {\n>  \t{ \"interpret-trailers\", cmd_interpret_trailers, RUN_SETUP_GENTLY },\n>  \t{ \"log\", cmd_log, RUN_SETUP },\n>  \t{ \"ls-files\", cmd_ls_files, RUN_SETUP },\n> -\t{ \"ls-remote\", cmd_ls_remote, RUN_SETUP_GENTLY },\n> +\t{ \"ls-remote\", cmd_ls_remote, RUN_SETUP_GENTLY | NO_INTERNAL_HELP },\n\nThere's only one other command that uses PARSE_OPT_NO_INTERNAL_HELP, and\nthat's \"git archive\".  Does it need the same treatment?\n\nMore generally, is there a straightforward way for parse-options or\nsome compile-time analysis to catch if we forget to add\nNO_INTERNAL_HELP to a command in the commands[] table?\n\nThanks,\nJonathan\n"},{"id":"330559","messageId":"CAN0heSpk+PPX7cAXT+jTZZ_LCAY=z6W4wxP38DqH89wST4PSWw@mail.gmail.com","threadId":"46970","inReplyTo":"f66f3fc2-8f51-03f5-c242-cb6d776af585@web.de","subject":"Re: [PATCH 2/2] ls-remote: use PARSE_OPT_NO_INTERNAL_HELP","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2017-10-17T17:42:46Z","receivedAt":"2017-10-17T17:42:52Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On 17 October 2017 at 17:39, René Scharfe <l.s.r@web.de> wrote:\n> Since ba5f28bf79 (ls-remote: use parse-options api) git ls-remote -h\n> without any other options has shown the short help text of the command\n> instead of acting as the short equivalent of --heads.  Fix this\n> regression by turning off internal handling of -h for repository setup,\n> and option parsing, as well as the corresponding test in t0012.\n>\n> Reported-by: Thomas Rikl <trikl@online.de>\n> Analyzed-by: Martin Ågren <martin.agren@gmail.com>\n> Signed-off-by: Rene Scharfe <l.s.r@web.de>\n> ---\n>  builtin/ls-remote.c  | 1 +\n>  git.c                | 2 +-\n>  t/t0012-help.sh      | 1 +\n>  t/t5512-ls-remote.sh | 6 ++++++\n>  4 files changed, 9 insertions(+), 1 deletion(-)\n\nDocumentation/gitcli.txt might need updating. It says that \"[c]ommands\nwhich have the enhanced option parser activated all understand ... -h\".\nOf course, it already was in an incorrect state, since it pretends like\nno-one uses PARSE_OPT_NO_INTERNAL_HELP. Probably better to leave that\nuntil it's clear in which direction \"git ls-remote -h\" should go.\n"},{"id":"330560","messageId":"20171017174350.4dnh3ydoagxgp6xj@aiede.mtv.corp.google.com","threadId":"46970","inReplyTo":"774f08bd-3172-0083-1544-e5f68f6798fa@web.de","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-10-17T17:43:50Z","receivedAt":"2017-10-17T17:43:57Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"René Scharfe wrote:\n\n> Stop advertising -h as the short equivalent of --heads, because it's\n> used for showing a short help text for almost all other git commands.\n> Since the ba5f28bf79 (ls-remote: use parse-options api) it has only\n> been working when used together with other parameters anyway.\n>\n> Signed-off-by: Rene Scharfe <l.s.r@web.de>\n> ---\n>  Documentation/git-ls-remote.txt | 1 -\n>  builtin/ls-remote.c             | 4 +++-\n>  2 files changed, 3 insertions(+), 2 deletions(-)\n\nYes, I think this is a good step.\nReviewed-by: Jonathan Nieder <jrnieder@gmail.com>\n\nI would be tempted to go even further and make \"git ls-remote -h\"\nprint a warning to stderr to encourage people to update their scripts\nto use --heads instead.\n\nThanks.\n"},{"id":"330580","messageId":"xmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com","threadId":"46970","inReplyTo":"774f08bd-3172-0083-1544-e5f68f6798fa@web.de","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-17T23:22:04Z","receivedAt":"2017-10-17T23:22:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"René Scharfe <l.s.r@web.de> writes:\n\n> Stop advertising -h as the short equivalent of --heads, because it's\n> used for showing a short help text for almost all other git commands.\n> Since the ba5f28bf79 (ls-remote: use parse-options api) it has only\n> been working when used together with other parameters anyway.\n>\n> Signed-off-by: Rene Scharfe <l.s.r@web.de>\n> ---\n> That would be step on the way towards more consistent command line\n> switches, in the same vein as d69155119 (t0012: test \"-h\" with\n> builtins).\n\nSorry, but I am not sure whom this and the other approach are trying\nto help.\n\nThe rule we have currently seems to be that \"git cmd -h\" (no other\narguments) consistently gives a short help, and if a subcommand\nsupports an option \"-h\" specific to it that is not about giving a\nshort help, the caller needs to be aware of it to invoke the option,\nby making sure that there is some other arguments on the command\nline if \"-h\" form of that subcommand specific option is used, by\ndoing e.g. \"git ls-remote -h origin\" or \"git ls-remote --head\".\n\nI can see that this \"alternative\" approach makes it less convenent\nfor folks who have followed that rule by hiding \"-h\" (with the\nintention of deprecating and possibly removing it in the future) and\nencouraging (and later foring) \"--head\" to be used instead.  \n\nThe other approach burdens new users by changing the rule to \"some\nsubcommands that have their own '-h' option cannot be asked for a\nbrief usage with 'git cmd -h'\".  But the thing is, these new users\nwho do not know which subcommands do have their own '-h' and which\nones do not are the ones that benefit most from the consistent \"'git\ncmd -h' with no other argument gets short help\" rule.\n\nWhen making a backward incompatible change, it is asking us to go to\nthose who are inconvenienced and say \"I am sorry that we are making\nthings less convenient for you, but by doing so we can gain this\ngreater good which is ...\".  I can explain how this and the other\napproach make things less convenient for existing or new users, but\nI am having a hard time formulating what the greater good is.\n\nIn short, I cannot sell this change to our users.  Please help me do\nso if you want this (or the other) change made to our system.\n\n"},{"id":"330658","messageId":"26112a15-f02c-a910-c8bb-794ca84dc1e5@web.de","threadId":"46970","inReplyTo":"xmqqk1ztmkbn.fsf@gitster.mtv.corp.google.com","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2017-10-19T18:26:47Z","receivedAt":"2017-10-19T18:27:26Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Am 18.10.2017 um 01:22 schrieb Junio C Hamano:\n> René Scharfe <l.s.r@web.de> writes:\n> \n>> Stop advertising -h as the short equivalent of --heads, because it's\n>> used for showing a short help text for almost all other git commands.\n>> Since the ba5f28bf79 (ls-remote: use parse-options api) it has only\n>> been working when used together with other parameters anyway.\n>>\n>> Signed-off-by: Rene Scharfe <l.s.r@web.de>\n>> ---\n>> That would be step on the way towards more consistent command line\n>> switches, in the same vein as d69155119 (t0012: test \"-h\" with\n>> builtins).\n> \n> Sorry, but I am not sure whom this and the other approach are trying\n> to help.\n> \n> The rule we have currently seems to be that \"git cmd -h\" (no other\n> arguments) consistently gives a short help, and if a subcommand\n> supports an option \"-h\" specific to it that is not about giving a\n> short help, the caller needs to be aware of it to invoke the option,\n> by making sure that there is some other arguments on the command\n> line if \"-h\" form of that subcommand specific option is used, by\n> doing e.g. \"git ls-remote -h origin\" or \"git ls-remote --head\".\n> \n> I can see that this \"alternative\" approach makes it less convenent\n> for folks who have followed that rule by hiding \"-h\" (with the\n> intention of deprecating and possibly removing it in the future) and\n> encouraging (and later foring) \"--head\" to be used instead.\n> \n> The other approach burdens new users by changing the rule to \"some\n> subcommands that have their own '-h' option cannot be asked for a\n> brief usage with 'git cmd -h'\".  But the thing is, these new users\n> who do not know which subcommands do have their own '-h' and which\n> ones do not are the ones that benefit most from the consistent \"'git\n> cmd -h' with no other argument gets short help\" rule.\n\nThey would help by aligning documentation and code, at a price.  But\nof course there is another way to do that -- I just didn't see it the\nother day.  We don't have to take anything away:\n\n-- >8 --\nSubject: [PATCH] ls-remote: document behavior of lone parameter -h\n\nReported-by: Thomas Rikl <trikl@online.de>\nAnalyzed-by: Martin Ågren <martin.agren@gmail.com>\nAnalyzed-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Rene Scharfe <l.s.r@web.de>\n---\n Documentation/git-ls-remote.txt | 10 ++++++++++\n builtin/ls-remote.c             |  5 ++++-\n 2 files changed, 14 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\nindex 5f2628c8f8..82622e7fbc 100644\n--- a/Documentation/git-ls-remote.txt\n+++ b/Documentation/git-ls-remote.txt\n@@ -29,6 +29,9 @@ OPTIONS\n \tThese options are _not_ mutually exclusive; when given\n \tboth, references stored in refs/heads and refs/tags are\n \tdisplayed.\n++\n+*NOTE*: -h without any other parameters shows a short help text instead\n+of any refs.\n \n --refs::\n \tDo not show peeled tags or pseudorefs like HEAD\tin the output.\n@@ -89,6 +92,13 @@ EXAMPLES\n \tf25a265a342aed6041ab0cc484224d9ca54b6f41\trefs/tags/v0.99.1\n \tc5db5456ae3b0873fc659c19fafdde22313cc441\trefs/tags/v0.99.2\n \t7ceca275d047c90c0c7d5afb13ab97efdf51bd6e\trefs/tags/v0.99.3\n+\t$ git ls-remote -hh\n+\tFrom https://git.kernel.org/pub/scm/git/git.git/\n+\t4c2224e83951a685185bb8c1f83b28e22fee0e27\trefs/heads/maint\n+\t5fe978a5381f1fbad26a80e682ddd2a401966740\trefs/heads/master\n+\t76aedb4517c834be2dc89efb5f9d15908e324422\trefs/heads/next\n+\tc781a84b5204fb294c9ccc79f8b3baceeb32c061\trefs/heads/pu\n+\t5d38b589ccc7a8355c62f1577865df5b8216c00d\trefs/heads/todo\n \n GIT\n ---\ndiff --git a/builtin/ls-remote.c b/builtin/ls-remote.c\nindex c4be98ab9e..0438dfec05 100644\n--- a/builtin/ls-remote.c\n+++ b/builtin/ls-remote.c\n@@ -56,7 +56,10 @@ int cmd_ls_remote(int argc, const char **argv, const char *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('h', NULL, &flags,\n+\t\t\tN_(\"if only parameter: show this help text, otherwise limit to heads\"),\n+\t\t\tREF_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.<base>.insteadOf into account\")),\n-- \n2.14.2\n"},{"id":"330678","messageId":"20171019203249.76uu3b6ferquitcr@sigill.intra.peff.net","threadId":"46970","inReplyTo":"26112a15-f02c-a910-c8bb-794ca84dc1e5@web.de","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-19T20:32:49Z","receivedAt":"2017-10-19T20:32:56Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Oct 19, 2017 at 08:26:47PM +0200, René Scharfe wrote:\n\n> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\n> index 5f2628c8f8..82622e7fbc 100644\n> --- a/Documentation/git-ls-remote.txt\n> +++ b/Documentation/git-ls-remote.txt\n> @@ -29,6 +29,9 @@ OPTIONS\n>  \tThese options are _not_ mutually exclusive; when given\n>  \tboth, references stored in refs/heads and refs/tags are\n>  \tdisplayed.\n> ++\n> +*NOTE*: -h without any other parameters shows a short help text instead\n> +of any refs.\n\nYuck. This \"we only treat -h as special in certain cases\" rule is\nsufficiently magical that I don't think we want to advertise and lock\nourselves into it.\n\n-Peff\n"},{"id":"330700","messageId":"xmqqlgk6iq94.fsf@gitster.mtv.corp.google.com","threadId":"46970","inReplyTo":"20171019203249.76uu3b6ferquitcr@sigill.intra.peff.net","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-20T01:04:23Z","receivedAt":"2017-10-20T01:04:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> On Thu, Oct 19, 2017 at 08:26:47PM +0200, René Scharfe wrote:\n>\n>> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt\n>> index 5f2628c8f8..82622e7fbc 100644\n>> --- a/Documentation/git-ls-remote.txt\n>> +++ b/Documentation/git-ls-remote.txt\n>> @@ -29,6 +29,9 @@ OPTIONS\n>>  \tThese options are _not_ mutually exclusive; when given\n>>  \tboth, references stored in refs/heads and refs/tags are\n>>  \tdisplayed.\n>> ++\n>> +*NOTE*: -h without any other parameters shows a short help text instead\n>> +of any refs.\n>\n> Yuck. This \"we only treat -h as special in certain cases\" rule is\n> sufficiently magical that I don't think we want to advertise and lock\n> ourselves into it.\n\nHmph.  I think it is way too late to be worried about \"locked into\"\nthe convention---hasn't the \"git cmd -h\" been with us forever?\n\nBesides, I personally feel that there is nothing magical in the rule\nthat is \"we always treat 'git $cmd -h' as asking for short help, but\nindividual subcommand may choose to use -h for, perhaps to be\ncompatible with other tools and conventions, in other situations\".\n"},{"id":"330709","messageId":"20171020030524.4xlwrdag7e4gzg7s@sigill.intra.peff.net","threadId":"46970","inReplyTo":"xmqqlgk6iq94.fsf@gitster.mtv.corp.google.com","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-20T03:05:25Z","receivedAt":"2017-10-20T03:05:36Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Oct 20, 2017 at 10:04:23AM +0900, Junio C Hamano wrote:\n\n> > Yuck. This \"we only treat -h as special in certain cases\" rule is\n> > sufficiently magical that I don't think we want to advertise and lock\n> > ourselves into it.\n> \n> Hmph.  I think it is way too late to be worried about \"locked into\"\n> the convention---hasn't the \"git cmd -h\" been with us forever?\n\nI guess. I still find it pretty nasty (not that \"-h\" works for help, but\nthat it can override the normal usage).\n\n> Besides, I personally feel that there is nothing magical in the rule\n> that is \"we always treat 'git $cmd -h' as asking for short help, but\n> individual subcommand may choose to use -h for, perhaps to be\n> compatible with other tools and conventions, in other situations\".\n\n<shrug> It seems weird and inconsistent to me that the meaning of \"-h\"\ndepends on the position and presence of other unrelated options. Maybe\nit's just me. I know _why_ it's that way, but this seems like one of\nthose weird corners of the interface that end up confusing people and\ngiving Git's interface the reputation of being full of mysterious\ninconsistencies. I suspect one of the reasons nobody has complained\nabout it is that \"ls-remote\" is not commonly used, and \"ls-remote -h\"\nless so (I didn't even know it was there until this conversation).\n\n-Peff\n"},{"id":"330712","messageId":"xmqq7evqidp3.fsf@gitster.mtv.corp.google.com","threadId":"46970","inReplyTo":"20171020030524.4xlwrdag7e4gzg7s@sigill.intra.peff.net","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-20T05:35:36Z","receivedAt":"2017-10-20T05:35:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> <shrug> It seems weird and inconsistent to me that the meaning of \"-h\"\n> depends on the position and presence of other unrelated options. Maybe\n> it's just me. I know _why_ it's that way, but this seems like one of\n> those weird corners of the interface that end up confusing people and\n> giving Git's interface the reputation of being full of mysterious\n> inconsistencies. I suspect one of the reasons nobody has complained\n> about it is that \"ls-remote\" is not commonly used, and \"ls-remote -h\"\n> less so (I didn't even know it was there until this conversation).\n\nTechnically, yes, it may be weird.\n\nI may be biased as every time I think about this one, the first one\nthat comes to my mind is how \"grep -h\" (not \"git grep\", but GNU\ngrep) behaves.  Yes, \"-h\" means something else, but by itself, the\ncommand does not make sense, and \"ls-remote -h\" is an exception to\nthe rule: most sane commands do not have a sensible semantics when\nthey take only \"-h\" and nothing else.  And even for ls-remote it is\ntrue only when you try to be extra lazy and do not say which remote\nyou are asking.\n\nAnd that is why I think \"'cmd -h\" and nothing else consistently\ngives help\" may overall be positive in usability, than a rule that\nsays \"'cmd -h' is for short-help unless -h means something else for\nthe command\".\n"},{"id":"330781","messageId":"20171021071613.yynmigxiixnqggik@sigill.intra.peff.net","threadId":"46970","inReplyTo":"xmqq7evqidp3.fsf@gitster.mtv.corp.google.com","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2017-10-21T07:16:14Z","receivedAt":"2017-10-21T07:16:25Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Oct 20, 2017 at 02:35:36PM +0900, Junio C Hamano wrote:\n\n> I may be biased as every time I think about this one, the first one\n> that comes to my mind is how \"grep -h\" (not \"git grep\", but GNU\n> grep) behaves.  Yes, \"-h\" means something else, but by itself, the\n> command does not make sense, and \"ls-remote -h\" is an exception to\n> the rule: most sane commands do not have a sensible semantics when\n> they take only \"-h\" and nothing else.  And even for ls-remote it is\n> true only when you try to be extra lazy and do not say which remote\n> you are asking.\n\nYeah, I have to admit \"grep -h\" is a lot more compelling, since it\nmatches normal grep. And I've used \"grep -h\" many times without thinking\nabout it, simply because the rule just falls out naturally there\n(there's nothing possible to do without a regex argument, so we'd show\nthe usage either way).\n\n> And that is why I think \"'cmd -h\" and nothing else consistently\n> gives help\" may overall be positive in usability, than a rule that\n> says \"'cmd -h' is for short-help unless -h means something else for\n> the command\".\n\nYeah, I was shooting more for \"let's avoid assigning -h to things\". But\nthat's not really possible if we want to be consistent with upstream\ngrep, which is probably more important.\n\nI think you've convinced me.\n\n-Peff\n"},{"id":"330785","messageId":"437f4e47-fcb1-ff8c-3c5a-fa9a5cecedfe@web.de","threadId":"46970","inReplyTo":"xmqq7evqidp3.fsf@gitster.mtv.corp.google.com","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2017-10-21T10:14:35Z","receivedAt":"2017-10-21T10:14:57Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Am 20.10.2017 um 07:35 schrieb Junio C Hamano:\n> Jeff King <peff@peff.net> writes:\n> \n>> <shrug> It seems weird and inconsistent to me that the meaning of \"-h\"\n>> depends on the position and presence of other unrelated options.\n\nThe position is relevant with parse-options for *each* flag for a\ndifferent reason as well: You can't put a flag after a non-flag.  I\nfind that more annoying, as it slightly but noticeable slows down\nadding a flag to a previous command by requiring to navigate to the\nmiddle of the line.\n\n(I guess I should train myself to use Meta-b for going back one word\nmore often..)\n\n> I may be biased as every time I think about this one, the first one\n> that comes to my mind is how \"grep -h\" (not \"git grep\", but GNU\n> grep) behaves.  Yes, \"-h\" means something else, but by itself, the\n> command does not make sense, and \"ls-remote -h\" is an exception to\n> the rule: most sane commands do not have a sensible semantics when\n> they take only \"-h\" and nothing else.  And even for ls-remote it is\n> true only when you try to be extra lazy and do not say which remote\n> you are asking.\n> \n> And that is why I think \"'cmd -h\" and nothing else consistently\n> gives help\" may overall be positive in usability, than a rule that\n> says \"'cmd -h' is for short-help unless -h means something else for\n> the command\".\n\nFWIW, I use \"-?\" for that everywhere.  I have yet to find a command or\nenvironment where it does something dangerous.\n\nRené\n"},{"id":"330787","messageId":"xmqqh8usg0cs.fsf@gitster.mtv.corp.google.com","threadId":"46970","inReplyTo":"437f4e47-fcb1-ff8c-3c5a-fa9a5cecedfe@web.de","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-21T12:18:59Z","receivedAt":"2017-10-21T12:19:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"René Scharfe <l.s.r@web.de> writes:\n\n> FWIW, I use \"-?\" for that everywhere.  I have yet to find a command or\n> environment where it does something dangerous.\n\nYeah, it would have made the world a better place if we made that\nchoice back in 2008.  If we start a transition to make it so right\nnow, we might be able to make the world a better place by 2022,\nperhaps.  I am not sure if the pain during the transition is worth\nit, though.\n"},{"id":"330837","messageId":"7c53071a-5154-1246-d2f1-1064e3f923d4@web.de","threadId":"46970","inReplyTo":"xmqqh8usg0cs.fsf@gitster.mtv.corp.google.com","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2017-10-23T15:05:23Z","receivedAt":"2017-10-23T15:05:40Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Am 21.10.2017 um 14:18 schrieb Junio C Hamano:\n> René Scharfe <l.s.r@web.de> writes:\n> \n>> FWIW, I use \"-?\" for that everywhere.  I have yet to find a command or\n>> environment where it does something dangerous.\n> \n> Yeah, it would have made the world a better place if we made that\n> choice back in 2008.  If we start a transition to make it so right\n> now, we might be able to make the world a better place by 2022,\n> perhaps.  I am not sure if the pain during the transition is worth\n> it, though.\n\n\"-?\" works fine with builtins already -- they complain that the option\nis unknown and then show the short help text.\n\nIf we removed the special handling for \"-h\" from parse-options it would\ndo the same for most commands, i.e. we'd get an additional error\nmessage, followed by the short help text that we're used to see.  We\ncould check for \"git grep -h\" without any other arguments and show the\nusage text in that case.  We could do the same for \"git ls-remote -h\"\nas well, but I'm not sure we want to.\n\nSo the cost would be an extra error message in most cases, and possibly\nthe inability to show help with \"git ls-remote -h\".  That doesn't sound\nvery painful.\n\nRené\n"},{"id":"330877","messageId":"xmqqbmkxbc45.fsf@gitster.mtv.corp.google.com","threadId":"46970","inReplyTo":"7c53071a-5154-1246-d2f1-1064e3f923d4@web.de","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-10-24T00:52:58Z","receivedAt":"2017-10-24T00:53:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"René Scharfe <l.s.r@web.de> writes:\n\n> Am 21.10.2017 um 14:18 schrieb Junio C Hamano:\n>> René Scharfe <l.s.r@web.de> writes:\n>> \n>>> FWIW, I use \"-?\" for that everywhere.  I have yet to find a command or\n>>> environment where it does something dangerous.\n>> \n>> Yeah, it would have made the world a better place if we made that\n>> choice back in 2008.  If we start a transition to make it so right\n>> now, we might be able to make the world a better place by 2022,\n>> perhaps.  I am not sure if the pain during the transition is worth\n>> it, though.\n>\n> \"-?\" works fine with builtins already -- they complain that the option\n> is unknown and then show the short help text.\n\nAh, I misunderstood what you meant, then.  I thought you were\nadvocating to move the built-in short-help support to know about and\nexplicitly react to \"-?\", and somehow forgot that it \"works\" more or\nless already.\n\nThe fact that \"-?\" already works for most things is good, but the\ntransition pain still remains, as what's costly is to transition\npeople's expectation (i.e. \"'-?' and not '-h' is the way to get\nshort help from any subcommand\"), not the implementation to fill the\ngaps for those that do not yet support '-?', I am afraid.\n\n"},{"id":"330931","messageId":"85e7beba-6f37-423b-24f1-2ad9da389846@web.de","threadId":"46970","inReplyTo":"xmqqbmkxbc45.fsf@gitster.mtv.corp.google.com","subject":"Re: [Alt. PATCH] ls-remote: deprecate -h as short for --heads","fromName":"René Scharfe","fromEmail":"l.s.r@web.de","sentAt":"2017-10-24T18:26:44Z","receivedAt":"2017-10-24T18:26:58Z","isPatch":true,"sender":{"key":"l.s.r@web.de","avatar":"https://avatars.githubusercontent.com/u/26122331?v=4"},"body":"Am 24.10.2017 um 02:52 schrieb Junio C Hamano:\n> René Scharfe <l.s.r@web.de> writes:\n> \n>> Am 21.10.2017 um 14:18 schrieb Junio C Hamano:\n>>> René Scharfe <l.s.r@web.de> writes:\n>>>\n>>>> FWIW, I use \"-?\" for that everywhere.  I have yet to find a command or\n>>>> environment where it does something dangerous.\n>>>\n>>> Yeah, it would have made the world a better place if we made that\n>>> choice back in 2008.  If we start a transition to make it so right\n>>> now, we might be able to make the world a better place by 2022,\n>>> perhaps.  I am not sure if the pain during the transition is worth\n>>> it, though.\n>>\n>> \"-?\" works fine with builtins already -- they complain that the option\n>> is unknown and then show the short help text.\n> \n> Ah, I misunderstood what you meant, then.  I thought you were\n> advocating to move the built-in short-help support to know about and\n> explicitly react to \"-?\", and somehow forgot that it \"works\" more or\n> less already.\n\nI don't mean to advocate here -- it's more like trying to get the\naccounting right.  A little bit of OCD perhaps?\n\n> The fact that \"-?\" already works for most things is good, but the\n> transition pain still remains, as what's costly is to transition\n> people's expectation (i.e. \"'-?' and not '-h' is the way to get\n> short help from any subcommand\"), not the implementation to fill the\n> gaps for those that do not yet support '-?', I am afraid.\n\nA minor cost for help-seeking users would be the extra error message at\nthe top of the short help text.\n\nThe main change would cause \"git ls-remote -h\" to show remote heads and\n\"git show-ref -h\" to show HEAD.  Confused users would have to resort to\ne.g. man, -help, --help, their search engine of choice, or -?.  I feel\nthis could be justified.  It would be different if e.g. reset started\nto take -h as shorthand for --hard, as this would cause data loss.\n\nThe hard part would probably be allowing the execution of commands with\nunknown arguments outside of repositories to show the help text, even\nif they'd normally (with correct arguments) require one.  Converting\nall commands from RUN_SETUP to RUN_SETUP_GENTLY seems painful.  Showing\nhelp when a required repo is not found might be possible somehow.\n\nWith that I'm going to shut up, as I don't even use the affected\ncommands, nor can I imagine being in the place of someone impacted by\n\"git <something> -h\" not showing a help text.\n\nRené\n"}]}