{"thread":{"id":"33148","subject":"[PATCH/RFC] Make help behaviour more consistent","startedAt":"2013-03-10T17:48:49Z","lastAt":"2013-03-11T21:50:31Z","messageCount":8,"participants":["Kevin Bracey","Philip Oakley","Junio C Hamano","Matthieu Moy"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"210988","messageId":"1362937729-9050-1-git-send-email-kevin@bracey.fi","threadId":"33148","inReplyTo":null,"subject":"[PATCH/RFC] Make help behaviour more consistent","fromName":"Kevin Bracey","fromEmail":"kevin@bracey.fi","sentAt":"2013-03-10T17:48:49Z","receivedAt":"2013-03-10T17:48:49Z","isPatch":true,"sender":{"key":"kevin@bracey.fi","avatar":"https://avatars.githubusercontent.com/u/96079793?v=4"},"body":"Previously, the command \"help\" and the option \"-h\" behaved differently\ndepending on whether a command was specified or not. Old user interface:\n\nCommands with no defaults show usage: \"git\" \"git CMD\"\nTo specifically request usage: \"git help\" \"git CMD -h\"\nTo get a manual page: \"git help git\" \"git help CMD\"\n\nTwo significant usability flaws here:\n - If using man, \"man git\" to side-step \"git help\" is obvious. But if\n trying to use help.format=web, how to get the root html page? My\n technique was \"git help XXX\" and click the \"git(1) suite\" link at the\n bottom. \"git help git\" is non-obvious and apparently undocumented\n (it's not mentioned by \"git\", \"git help\", or \"git help help\"...).\n\n - Because git itself didn't support -h (and thus actually printed less\n if you specified it), the general availability of -h for commands was\n non-obvious. I didn't know about it until I started this patch.\n\nTidy this up, so that help and -h do not change behaviour depending on\nwhether a command is specified or not. New, consistent user interface:\n\nCommands with no defaults show usage: \"git\" \"git CMD\"\nTo specifically request usage: \"git -h\" \"git CMD -h\"\nTo get a manual page: \"git help\" \"git help CMD\".\n\n\"git help git\" is still accepted. The legacy \"--help\" option behaves as\nbefore, which means \"git --help\" on its own is now a synonym for \"git\n-h\", not \"git help\", and it remains consistent with GNU Coding\nGuidelines.\n\nSo the only change to existing command behaviour is that \"git help\" or\n\"git help -w\" now opens the git manual page, rather than showing common\ncommands.\n\n\"git -h cmd\" is also accepted as a synonym for \"git cmd -h\", as per\nLinus's rationale for treating \"git cmd --help\" as a synonym for \"git\n--help cmd\".\n\nOption list shown in command-line usage re-ordered to match the manual\npage, and git and git-help manual pages edited to reflect the new help\nbehaviour.\n\nSigned-off-by: Kevin Bracey \n---\n Documentation/git-help.txt | 22 +++++++++-------------\n Documentation/git.txt | 17 ++++++++---------\n builtin/help.c | 9 +--------\n git.c | 40 +++++++++++++++++++++++-----------------\n 4 files changed, 41 insertions(+), 47 deletions(-)\n\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex e07b6dc..25def9f 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -13,19 +13,16 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-With no options and no COMMAND given, the synopsis of the 'git'\n-command and a list of the most commonly used Git commands are printed\n-on the standard output.\n-\n If the option '--all' or '-a' is given, then all available commands are\n printed on the standard output.\n \n-If a Git subcommand is named, a manual page for that subcommand is brought\n+Otherwise, a manual page for Git or the specified Git command is brought\n up. The 'man' program is used by default for this purpose, but this\n can be overridden by other options or configuration variables.\n \n Note that `git --help ...` is identical to `git help ...` because the\n-former is internally converted into the latter.\n+former is internally converted into the latter. Also, to supplement\n+`git help`, most Git commands offer the option '-h' to print usage.\n \n OPTIONS\n -------\n@@ -36,14 +33,13 @@ OPTIONS\n \n -i::\n --info::\n-\tDisplay manual page for the command in the 'info' format. The\n-\t'info' program will be used for that purpose.\n+\tDisplay manual page in the 'info' format. The 'info' program will\n+\tbe used for that purpose.\n \n -m::\n --man::\n-\tDisplay manual page for the command in the 'man' format. This\n-\toption may be used to override a value set in the\n-\t'help.format' configuration variable.\n+\tDisplay manual page in the 'man' format. This option may be used to\n+\toverride a value set in the 'help.format' configuration variable.\n +\n By default the 'man' program will be used to display the manual page,\n but the 'man.viewer' configuration variable may be used to choose\n@@ -51,8 +47,8 @@ other display programs (see below).\n \n -w::\n --web::\n-\tDisplay manual page for the command in the 'web' (HTML)\n-\tformat. A web browser will be used for that purpose.\n+\tDisplay manual page in the 'web' (HTML)\tformat. A web browser will\n+\tbe used for that purpose.\n +\n The web browser can be specified using the configuration variable\n 'help.browser', or 'web.browser' if the former is not set. If none of\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 9d29ed5..51cdca2 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -9,7 +9,7 @@ git - the stupid content tracker\n SYNOPSIS\n --------\n [verse]\n-'git' [--version] [--help] [-c =]\n+'git' [--version] [--help] [-h] [-c =]\n [--exec-path[=]] [--html-path] [--man-path] [--info-path]\n [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]\n [--git-dir=] [--work-tree=] [--namespace=]\n@@ -361,16 +361,15 @@ OPTIONS\n --version::\n \tPrints the Git suite version that the 'git' program came from.\n \n---help::\n+-h::\n \tPrints the synopsis and a list of the most commonly used\n-\tcommands. If the option '--all' or '-a' is given then all\n-\tavailable commands are printed. If a Git command is named this\n-\toption will bring up the manual page for that command.\n+\tcommands. Most Git commands also provide a '-h'\toption to\n+\tshow their own synopsis.\n +\n-Other options are available to control how the manual page is\n-displayed. See linkgit:git-help[1] for more information,\n-because `git --help ...` is converted internally into `git\n-help ...`.\n+For compatibility, `git --help` is also implemented. With no\n+following options, it is equivalent to `git -h`. Otherwise it is\n+converted internally into `git help ...`, which will open a manual\n+page. See linkgit:git-help[1] for more information.\n \n -c =::\n \tPass a configuration parameter to the command. The value\ndiff --git a/builtin/help.c b/builtin/help.c\nindex d1d7181..ef4706a 100644\n--- a/builtin/help.c\n+++ b/builtin/help.c\n@@ -432,13 +432,6 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \t\treturn 0;\n \t}\n \n-\tif (!argv[0]) {\n-\t\tprintf(_(\"usage: %s%s\"), _(git_usage_string), \"\\n\\n\");\n-\t\tlist_common_cmds_help();\n-\t\tprintf(\"\\n%s\\n\", _(git_more_info_string));\n-\t\treturn 0;\n-\t}\n-\n \tsetup_git_directory_gently(&nongit);\n \tgit_config(git_help_config, NULL);\n \n@@ -447,7 +440,7 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n \tif (help_format == HELP_FORMAT_NONE)\n \t\thelp_format = parse_help_format(DEFAULT_HELP_FORMAT);\n \n-\talias = alias_lookup(argv[0]);\n+\talias = argv[0] ? alias_lookup(argv[0]) : NULL;\n \tif (alias && !is_git_command(argv[0])) {\n \t\tprintf_ln(_(\"`git %s' is aliased to `%s'\"), argv[0], alias);\n \t\treturn 0;\ndiff --git a/git.c b/git.c\nindex b10c18b..82a74c5 100644\n--- a/git.c\n+++ b/git.c\n@@ -6,10 +6,10 @@\n #include \"run-command.h\"\n \n const char git_usage_string[] =\n-\t\"git [--version] [--exec-path[=]] [--html-path] [--man-path] [--info-path]\\n\"\n+\t\"git [--version] [--help] [-h] [-c name=value]\\n\"\n+\t\" [--exec-path[=]] [--html-path] [--man-path] [--info-path]\\n\"\n \t\" [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]\\n\"\n \t\" [--git-dir=] [--work-tree=] [--namespace=]\\n\"\n-\t\" [-c name=value] [--help]\\n\"\n \t\" []\";\n \n const char git_more_info_string[] =\n@@ -17,6 +17,7 @@ const char git_more_info_string[] =\n \n static struct startup_info git_startup_info;\n static int use_pager = -1;\n+static int show_usage;\n \n static void commit_pager_choice(void) {\n \tswitch (use_pager) {\n@@ -40,17 +41,6 @@ static int handle_options(const char ***argv, int *argc, int *envchanged)\n \t\tif (cmd[0] != '-')\n \t\t\tbreak;\n \n-\t\t/*\n-\t\t * For legacy reasons, the \"version\" and \"help\"\n-\t\t * commands can be written with \"--\" prepended\n-\t\t * to make them look like flags.\n-\t\t */\n-\t\tif (!strcmp(cmd, \"--help\") || !strcmp(cmd, \"--version\"))\n-\t\t\tbreak;\n-\n-\t\t/*\n-\t\t * Check remaining flags.\n-\t\t */\n \t\tif (!prefixcmp(cmd, \"--exec-path\")) {\n \t\t\tcmd += 11;\n \t\t\tif (*cmd == '=')\n@@ -143,6 +133,25 @@ static int handle_options(const char ***argv, int *argc, int *envchanged)\n \t\t\tsetenv(GIT_LITERAL_PATHSPECS_ENVIRONMENT, \"0\", 1);\n \t\t\tif (envchanged)\n \t\t\t\t*envchanged = 1;\n+\t\t} else if (!strcmp(cmd, \"--version\")) {\n+\t\t\t/* Alternative spelling for \"git version\" */\n+\t\t\t(*argv)[0] += 2;\n+\t\t\tbreak;\n+\t\t} else if (!strcmp(cmd, \"--help\")) {\n+\t\t\tif (*argc > 1) {\n+\t\t\t\t/* Alternative spelling for \"git help XXX\" */\n+\t\t\t\t(*argv)[0] += 2;\n+\t\t\t\tbreak;\n+\t\t\t} else\n+\t\t\t\tshow_usage = 1;\n+\t\t} else if (!strcmp(cmd, \"-h\")) {\n+\t\t\tif (*argc > 1 && (*argv)[1][0] != '-') {\n+\t\t\t\t/* Turn \"git -h cmd\" into \"git cmd -h\" */\n+\t\t\t\t(*argv)[0] = (*argv)[1];\n+\t\t\t\t(*argv)[1] = \"-h\";\n+\t\t\t\tbreak;\n+\t\t\t} else\n+\t\t\t\tshow_usage = 1;\n \t\t} else {\n \t\t\tfprintf(stderr, \"Unknown option: %s\\n\", cmd);\n \t\t\tusage(git_usage_string);\n@@ -537,10 +546,7 @@ int main(int argc, const char **argv)\n \targv++;\n \targc--;\n \thandle_options(&argv, &argc, NULL);\n-\tif (argc > 0) {\n-\t\tif (!prefixcmp(argv[0], \"--\"))\n-\t\t\targv[0] += 2;\n-\t} else {\n+\tif (argc <= 0 || show_usage) {\n \t\t/* The user didn't specify a command; give them help */\n \t\tcommit_pager_choice();\n \t\tprintf(\"usage: %s\\n\\n\", git_usage_string);\n-- \n1.8.2.rc3.7.g1100d09.dirty\n"},{"id":"211013","messageId":"513D1DBF.4050208@iee.org","threadId":"33148","inReplyTo":"1362937729-9050-1-git-send-email-kevin@bracey.fi","subject":"Re: [PATCH/RFC] Make help behaviour more consistent","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-03-10T23:56:47Z","receivedAt":"2013-03-10T23:56:47Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 10/03/13 17:48, Kevin Bracey wrote:\n> Previously, the command \"help\" and the option \"-h\" behaved differently\n> depending on whether a command was specified or not. Old user interface:\n>\n> Commands with no defaults show usage: \"git\" \"git CMD\"\n> To specifically request usage: \"git help\" \"git CMD -h\"\n> To get a manual page: \"git help git\" \"git help CMD\"\n>\n\nI agree they were inconsistent, but the change should also consider how \nthe help for 'git help' should be provided as well.\n\nI have some patches in preparation for also listing the commonly used \nguides, which can also be accessed by the existing `git help ` \ne.g. 'tutorial' (but not user-manual or everday git unfortunately).\n\nhttp://permalink.gmane.org/gmane.comp.version-control.git/217354\n\nI have a new version in prep but my ubuntu m/c is out of action.\n\n> Two significant usability flaws here:\n> - If using man, \"man git\" to side-step \"git help\" is obvious. But if\n> trying to use help.format=web, how to get the root html page? My\n> technique was \"git help XXX\" and click the \"git(1) suite\" link at the\n> bottom. \"git help git\" is non-obvious and apparently undocumented\n> (it's not mentioned by \"git\", \"git help\", or \"git help help\"...).\n>\n> - Because git itself didn't support -h (and thus actually printed less\n> if you specified it), the general availability of -h for commands was\n> non-obvious. I didn't know about it until I started this patch.\n>\n> Tidy this up, so that help and -h do not change behaviour depending on\n> whether a command is specified or not. New, consistent user interface:\n>\n> Commands with no defaults show usage: \"git\" \"git CMD\"\n> To specifically request usage: \"git -h\" \"git CMD -h\"\n> To get a manual page: \"git help\" \"git help CMD\".\n>\n> \"git help git\" is still accepted. The legacy \"--help\" option behaves as\n> before, which means \"git --help\" on its own is now a synonym for \"git\n> -h\", not \"git help\", and it remains consistent with GNU Coding\n> Guidelines.\n>\n> So the only change to existing command behaviour is that \"git help\" or\n> \"git help -w\" now opens the git manual page, rather than showing common\n> commands.\n>\n> \"git -h cmd\" is also accepted as a synonym for \"git cmd -h\", as per\n> Linus's rationale for treating \"git cmd --help\" as a synonym for \"git\n> --help cmd\".\n>\n> Option list shown in command-line usage re-ordered to match the manual\n> page, and git and git-help manual pages edited to reflect the new help\n> behaviour.\n>\n> Signed-off-by: Kevin Bracey \n> ---\n> Documentation/git-help.txt | 22 +++++++++-------------\n> Documentation/git.txt | 17 ++++++++---------\n> builtin/help.c | 9 +--------\n> git.c | 40 +++++++++++++++++++++++-----------------\n> 4 files changed, 41 insertions(+), 47 deletions(-)\n>\n> diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\n> index e07b6dc..25def9f 100644\n> --- a/Documentation/git-help.txt\n> +++ b/Documentation/git-help.txt\n> @@ -13,19 +13,16 @@ SYNOPSIS\n> DESCRIPTION\n> -----------\n>\n> -With no options and no COMMAND given, the synopsis of the 'git'\n> -command and a list of the most commonly used Git commands are printed\n> -on the standard output.\n> -\n> If the option '--all' or '-a' is given, then all available commands are\n> printed on the standard output.\n>\n> -If a Git subcommand is named, a manual page for that subcommand is brought\n> +Otherwise, a manual page for Git or the specified Git command is brought\n> up. The 'man' program is used by default for this purpose, but this\n> can be overridden by other options or configuration variables.\n>\n> Note that `git --help ...` is identical to `git help ...` because the\n> -former is internally converted into the latter.\n> +former is internally converted into the latter. Also, to supplement\n> +`git help`, most Git commands offer the option '-h' to print usage.\n>\n> OPTIONS\n> -------\n> @@ -36,14 +33,13 @@ OPTIONS\n>\n> -i::\n> --info::\n> -\tDisplay manual page for the command in the 'info' format. The\n> -\t'info' program will be used for that purpose.\n> +\tDisplay manual page in the 'info' format. The 'info' program will\n> +\tbe used for that purpose.\n>\n> -m::\n> --man::\n> -\tDisplay manual page for the command in the 'man' format. This\n> -\toption may be used to override a value set in the\n> -\t'help.format' configuration variable.\n> +\tDisplay manual page in the 'man' format. This option may be used to\n> +\toverride a value set in the 'help.format' configuration variable.\n> +\n> By default the 'man' program will be used to display the manual page,\n> but the 'man.viewer' configuration variable may be used to choose\n> @@ -51,8 +47,8 @@ other display programs (see below).\n>\n> -w::\n> --web::\n> -\tDisplay manual page for the command in the 'web' (HTML)\n> -\tformat. A web browser will be used for that purpose.\n> +\tDisplay manual page in the 'web' (HTML)\tformat. A web browser will\n> +\tbe used for that purpose.\n> +\n> The web browser can be specified using the configuration variable\n> 'help.browser', or 'web.browser' if the former is not set. If none of\n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index 9d29ed5..51cdca2 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -9,7 +9,7 @@ git - the stupid content tracker\n> SYNOPSIS\n> --------\n> [verse]\n> -'git' [--version] [--help] [-c =]\n> +'git' [--version] [--help] [-h] [-c =]\n> [--exec-path[=]] [--html-path] [--man-path] [--info-path]\n> [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]\n> [--git-dir=] [--work-tree=] [--namespace=]\n> @@ -361,16 +361,15 @@ OPTIONS\n> --version::\n> \tPrints the Git suite version that the 'git' program came from.\n>\n> ---help::\n> +-h::\n> \tPrints the synopsis and a list of the most commonly used\n> -\tcommands. If the option '--all' or '-a' is given then all\n> -\tavailable commands are printed. If a Git command is named this\n> -\toption will bring up the manual page for that command.\n> +\tcommands. Most Git commands also provide a '-h'\toption to\n> +\tshow their own synopsis.\n> +\n> -Other options are available to control how the manual page is\n> -displayed. See linkgit:git-help[1] for more information,\n> -because `git --help ...` is converted internally into `git\n> -help ...`.\n> +For compatibility, `git --help` is also implemented. With no\n> +following options, it is equivalent to `git -h`. Otherwise it is\n> +converted internally into `git help ...`, which will open a manual\n> +page. See linkgit:git-help[1] for more information.\n>\n> -c =::\n> \tPass a configuration parameter to the command. The value\n> diff --git a/builtin/help.c b/builtin/help.c\n> index d1d7181..ef4706a 100644\n> --- a/builtin/help.c\n> +++ b/builtin/help.c\n> @@ -432,13 +432,6 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n> \t\treturn 0;\n> \t}\n>\n> -\tif (!argv[0]) {\n> -\t\tprintf(_(\"usage: %s%s\"), _(git_usage_string), \"\\n\\n\");\n> -\t\tlist_common_cmds_help();\n> -\t\tprintf(\"\\n%s\\n\", _(git_more_info_string));\n> -\t\treturn 0;\n> -\t}\n> -\n> \tsetup_git_directory_gently(&nongit);\n> \tgit_config(git_help_config, NULL);\n>\n> @@ -447,7 +440,7 @@ int cmd_help(int argc, const char **argv, const char *prefix)\n> \tif (help_format == HELP_FORMAT_NONE)\n> \t\thelp_format = parse_help_format(DEFAULT_HELP_FORMAT);\n>\n> -\talias = alias_lookup(argv[0]);\n> +\talias = argv[0] ? alias_lookup(argv[0]) : NULL;\n> \tif (alias && !is_git_command(argv[0])) {\n> \t\tprintf_ln(_(\"`git %s' is aliased to `%s'\"), argv[0], alias);\n> \t\treturn 0;\n> diff --git a/git.c b/git.c\n> index b10c18b..82a74c5 100644\n> --- a/git.c\n> +++ b/git.c\n> @@ -6,10 +6,10 @@\n> #include \"run-command.h\"\n>\n> const char git_usage_string[] =\n> -\t\"git [--version] [--exec-path[=]] [--html-path] [--man-path] [--info-path]\\n\"\n> +\t\"git [--version] [--help] [-h] [-c name=value]\\n\"\n> +\t\" [--exec-path[=]] [--html-path] [--man-path] [--info-path]\\n\"\n> \t\" [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]\\n\"\n> \t\" [--git-dir=] [--work-tree=] [--namespace=]\\n\"\n> -\t\" [-c name=value] [--help]\\n\"\n> \t\" []\";\n>\n> const char git_more_info_string[] =\n> @@ -17,6 +17,7 @@ const char git_more_info_string[] =\n>\n> static struct startup_info git_startup_info;\n> static int use_pager = -1;\n> +static int show_usage;\n>\n> static void commit_pager_choice(void) {\n> \tswitch (use_pager) {\n> @@ -40,17 +41,6 @@ static int handle_options(const char ***argv, int *argc, int *envchanged)\n> \t\tif (cmd[0] != '-')\n> \t\t\tbreak;\n>\n> -\t\t/*\n> -\t\t * For legacy reasons, the \"version\" and \"help\"\n> -\t\t * commands can be written with \"--\" prepended\n> -\t\t * to make them look like flags.\n> -\t\t */\n> -\t\tif (!strcmp(cmd, \"--help\") || !strcmp(cmd, \"--version\"))\n> -\t\t\tbreak;\n> -\n> -\t\t/*\n> -\t\t * Check remaining flags.\n> -\t\t */\n> \t\tif (!prefixcmp(cmd, \"--exec-path\")) {\n> \t\t\tcmd += 11;\n> \t\t\tif (*cmd == '=')\n> @@ -143,6 +133,25 @@ static int handle_options(const char ***argv, int *argc, int *envchanged)\n> \t\t\tsetenv(GIT_LITERAL_PATHSPECS_ENVIRONMENT, \"0\", 1);\n> \t\t\tif (envchanged)\n> \t\t\t\t*envchanged = 1;\n> +\t\t} else if (!strcmp(cmd, \"--version\")) {\n> +\t\t\t/* Alternative spelling for \"git version\" */\n> +\t\t\t(*argv)[0] += 2;\n> +\t\t\tbreak;\n> +\t\t} else if (!strcmp(cmd, \"--help\")) {\n> +\t\t\tif (*argc > 1) {\n> +\t\t\t\t/* Alternative spelling for \"git help XXX\" */\n> +\t\t\t\t(*argv)[0] += 2;\n> +\t\t\t\tbreak;\n> +\t\t\t} else\n> +\t\t\t\tshow_usage = 1;\n> +\t\t} else if (!strcmp(cmd, \"-h\")) {\n> +\t\t\tif (*argc > 1 && (*argv)[1][0] != '-') {\n> +\t\t\t\t/* Turn \"git -h cmd\" into \"git cmd -h\" */\n> +\t\t\t\t(*argv)[0] = (*argv)[1];\n> +\t\t\t\t(*argv)[1] = \"-h\";\n> +\t\t\t\tbreak;\n> +\t\t\t} else\n> +\t\t\t\tshow_usage = 1;\n> \t\t} else {\n> \t\t\tfprintf(stderr, \"Unknown option: %s\\n\", cmd);\n> \t\t\tusage(git_usage_string);\n> @@ -537,10 +546,7 @@ int main(int argc, const char **argv)\n> \targv++;\n> \targc--;\n> \thandle_options(&argv, &argc, NULL);\n> -\tif (argc > 0) {\n> -\t\tif (!prefixcmp(argv[0], \"--\"))\n> -\t\t\targv[0] += 2;\n> -\t} else {\n> +\tif (argc <= 0 || show_usage) {\n> \t\t/* The user didn't specify a command; give them help */\n> \t\tcommit_pager_choice();\n> \t\tprintf(\"usage: %s\\n\\n\", git_usage_string);\n>\n"},{"id":"211017","messageId":"7v1ubmd4dt.fsf@alter.siamese.dyndns.org","threadId":"33148","inReplyTo":"1362937729-9050-1-git-send-email-kevin@bracey.fi","subject":"Re: [PATCH/RFC] Make help behaviour more consistent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-11T03:03:42Z","receivedAt":"2013-03-11T03:03:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kevin Bracey writes:\n\n> Previously, the command \"help\" and the option \"-h\" behaved differently\n> depending on whether a command was specified or not. Old user interface:\n>\n> Commands with no defaults show usage: \"git\" \"git CMD\"\n> To specifically request usage: \"git help\" \"git CMD -h\"\n> To get a manual page: \"git help git\" \"git help CMD\"\n>\n> Two significant usability flaws here:\n> - If using man, \"man git\" to side-step \"git help\" is obvious. But if\n> trying to use help.format=web, how to get the root html page? My\n> technique was \"git help XXX\" and click the \"git(1) suite\" link at the\n> bottom. \"git help git\" is non-obvious and apparently undocumented\n> (it's not mentioned by \"git\", \"git help\", or \"git help help\"...).\n>\n> - Because git itself didn't support -h (and thus actually printed less\n> if you specified it), the general availability of -h for commands was\n> non-obvious. I didn't know about it until I started this patch.\n\nHmm, I feel more confused than convinced after reading the above\nthree times. Perhaps that is because I am too used to the way how\n\"git\" potty itself behaves, especially the part that \"git help git\"\nis the way to ask \"git\" (the first token on the command line) to\ngive me \"help\" about \"git\" (the second) itself.\n\nHaving said that, I would agree that \"git -h\" that shows a \"unknown\noption\" error message that lists the supported command line options\n(just like how it reacts to \"git -x\") is less friendly than \"git\"\nthat knows \"-h\" to show the short help text, and that part of the\npatch is a definite improvement. But other than that I do not see\nany \"significant usablity flow\" in it.\n\nThe patch seems to do a lot more than just teaching \"git\" to react\nto \"-h\" to give a short usage, instead of doing the generic \"I do\nnot know -h option\" thing. I am not sure what merit these other\nchanges of this patch have.\n\nIn the introductory part, you list three possibilities, but there is\nthe fourth \"git help help\" to ask \"git\" to give me \"help\" about\n\"help\". Depending on where one comes from, that may also seem just\nas odd as \"git help git\" (again, I personally find neither is odd,\nthough). Would this change help with that \"usability flaw\" as well?\n\nUndecided...\n"},{"id":"211029","messageId":"vpq620yfj6g.fsf@grenoble-inp.fr","threadId":"33148","inReplyTo":"1362937729-9050-1-git-send-email-kevin@bracey.fi","subject":"Re: [PATCH/RFC] Make help behaviour more consistent","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2013-03-11T08:13:27Z","receivedAt":"2013-03-11T08:13:27Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Kevin Bracey writes:\n\n> Two significant usability flaws here:\n> - If using man, \"man git\" to side-step \"git help\" is obvious. But if\n> trying to use help.format=web, how to get the root html page? My\n> technique was \"git help XXX\" and click the \"git(1) suite\" link at the\n> bottom. \"git help git\" is non-obvious and apparently undocumented\n> (it's not mentioned by \"git\", \"git help\", or \"git help help\"...).\n\nCan't this be solved by adding something like\n\n See 'git help git' for general help about Git.\n\nto the output of \"git help\"? I think the fact that \"git help\" provides a\nsmall amount of output (typically: fits on one screen) is a nice feature\nthat avoids scaring people too early with the actual doc.\n\nThat said, I'm no longer a user of the short command list, so maybe I'm\nnot a good judge ;-).\n\n> Option list shown in command-line usage re-ordered to match the manual\n> page, and git and git-help manual pages edited to reflect the new help\n> behaviour.\n\nThis is typically better submitted as a separate patch. Putting\nuncontroversial changes in their own patches help the discussion to\nfocus on important changes, and avoids distracting the review.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"211096","messageId":"513E27AE.6050000@bracey.fi","threadId":"33148","inReplyTo":"7v1ubmd4dt.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH/RFC] Make help behaviour more consistent","fromName":"Kevin Bracey","fromEmail":"kevin@bracey.fi","sentAt":"2013-03-11T18:51:26Z","receivedAt":"2013-03-11T18:51:26Z","isPatch":true,"sender":{"key":"kevin@bracey.fi","avatar":"https://avatars.githubusercontent.com/u/96079793?v=4"},"body":"On 11/03/2013 05:03, Junio C Hamano wrote:\n> Hmm, I feel more confused than convinced after reading the above\n> three times. Perhaps that is because I am too used to the way how\n> \"git\" potty itself behaves, especially the part that \"git help git\"\n> is the way to ask \"git\" (the first token on the command line) to\n> give me \"help\" about \"git\" (the second) itself.\n\nBut you are nowhere told that \"git help\" will give you information on \nany topic other than Git commands. Starting from just typing \"git\", all \nyou are told is that you can type \"git help \". Given that \ninformation, you could at least logically deduce that \"git help help\" \nwill give you help on \"git help\". (Not that it would help anyway - even \ngit-help.txt doesn't say that you can specify anything other than a Git \ncommand, like \"git\" or \"cli\". But sounds like Philip's already on there \ncase there).\n\nIf you can figure out \"man git\" for yourself (and if it's available - \nWindows?) then from there you're explicitly told how to directly access \nall the other docs using man itself, including gitrevisions(7), etc.\n\nAnd having gotten to \"man gitrevisions\", I figured out that \"git help \nrevisions\" could get to the HTML equivalent. Not documented, but at \nleast fits the pattern, give or take a hyphen. But I never figured out \n\"git help git\", until I read the source. Why do I need to add the extra \n\"git\" to the help command for that page, and that page only? \"git\" isn't \na Git command, and there's no \"man gitgit\" topic! Even if I explicitly \ntry to point explicitly that I want a web page with \"git help -w\", I \ndon't get it...\n\nI think at the very minimum you need to make it explicitly clear right \nup front that \"git help git\" is available:\n\n See 'git help git' for more information on Git\nSee 'git help ' for more information on a specific command.\n\nSeems ugly though. I'm at a loss to understand why \"git help\", the \nmanual launching command, shouldn't by default simply launch the root of \nthe manual tree, rather than replicate the behaviour of \"git\"/\"git --help\".\n\nAnd something needs to be done to advertise the general existence of \nusage on commands. \"-h\" is currently hidden on page 4 of \"man gitcli\". \n(Is it anywhere else?) I've managed to avoid finding out about it for \nyears! Checking a few people around me, none of them knew about it either.\n\nAt the minute \"git\" tells you about \"git --help\", which shows usage, but \n\"git add --help\" launches the manual. (Huh?) Given that, I always \nassumed there was no usage available for individual commands - if there \nwas usage, surely it would be there on --help, like on \"git\". Never \noccurred to me it would be there under \"-h\" instead.\n\nSo how about going further than that patch, and making it even simpler. \nCollapse --help and -h to be synonyms. Then under either spelling, \n--help|-h always shows usage for \"git\" or \"git \", as per GNU \nguidelines.\n\nThen the manual launch only happens for \"git help ...\" and, \"git help\" \non its own launches the root. And the output of \"git [--help]\" ends with:\n\n See 'git help []' for more information.\n\nKevin\n"},{"id":"211067","messageId":"7vppz592v5.fsf@alter.siamese.dyndns.org","threadId":"33148","inReplyTo":"vpq620yfj6g.fsf@grenoble-inp.fr","subject":"Re: [PATCH/RFC] Make help behaviour more consistent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-11T19:02:22Z","receivedAt":"2013-03-11T19:02:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> Kevin Bracey writes:\n>\n>> Two significant usability flaws here:\n>> - If using man, \"man git\" to side-step \"git help\" is obvious. But if\n>> trying to use help.format=web, how to get the root html page? My\n>> technique was \"git help XXX\" and click the \"git(1) suite\" link at the\n>> bottom. \"git help git\" is non-obvious and apparently undocumented\n>> (it's not mentioned by \"git\", \"git help\", or \"git help help\"...).\n>\n> Can't this be solved by adding something like\n>\n> See 'git help git' for general help about Git.\n>\n> to the output of \"git help\"? I think the fact that \"git help\" provides a\n> small amount of output (typically: fits on one screen) is a nice feature\n> that avoids scaring people too early with the actual doc.\n\nThat sounds like a good direction to go in.\n"},{"id":"211077","messageId":"CD3017A6746B45FE8A5F242E4C597B51@PhilipOakley","threadId":"33148","inReplyTo":"7vppz592v5.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH/RFC] Make help behaviour more consistent","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2013-03-11T20:44:10Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \nSent: Monday, March 11, 2013 7:02 PM\n> Matthieu Moy writes:\n>\n>> Kevin Bracey writes:\n>>\n>>> Two significant usability flaws here:\n>>> - If using man, \"man git\" to side-step \"git help\" is obvious. But \n>>> if\n>>> trying to use help.format=web, how to get the root html page? My\n>>> technique was \"git help XXX\" and click the \"git(1) suite\" link at \n>>> the\n>>> bottom. \"git help git\" is non-obvious and apparently undocumented\n>>> (it's not mentioned by \"git\", \"git help\", or \"git help help\"...).\n>>\n>> Can't this be solved by adding something like\n>>\n>> See 'git help git' for general help about Git.\n>>\n>> to the output of \"git help\"? I think the fact that \"git help\" \n>> provides a\n>> small amount of output (typically: fits on one screen) is a nice \n>> feature\n>> that avoids scaring people too early with the actual doc.\n>\n> That sounds like a good direction to go in.\n\nMy earlier attempt, and Junio's reply \nhttp://thread.gmane.org/gmane.comp.version-control.git/217352\n\nIt is tricky making sure that the message covers help for git, help's \nown help,\nthe guides, and the commands, all in one compact usage line, while also\ncovering the -h and --help options (which may not be known to new Git\nusers on Windows, though probably obvious to Linux/Unix users).\n\nPhilip \n"},{"id":"211084","messageId":"7vhakh8v2w.fsf@alter.siamese.dyndns.org","threadId":"33148","inReplyTo":"CD3017A6746B45FE8A5F242E4C597B51@PhilipOakley","subject":"Re: [PATCH/RFC] Make help behaviour more consistent","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-11T21:50:31Z","receivedAt":"2013-03-11T21:50:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> From: \"Junio C Hamano\" \n>> Matthieu Moy writes:\n>>\n>>> See 'git help git' for general help about Git.\n>>>\n>>> to the output of \"git help\"?\n>> ...\n>> That sounds like a good direction to go in.\n>\n> My earlier attempt, and Junio's reply\n> http://thread.gmane.org/gmane.comp.version-control.git/217352\n\nYeah, I threw \"git help git\" in the general category of \"git help\n\" in that message, and now I realize that it may arguably be\nconfusing to some people.\n\nPerhaps spend one more line to do something like this?\n\n 'git help -a' and 'git help -g' lists available subcommands and\n concept guides. See 'git help ' or 'git help '\n to read about a specific subcommand or concept.\n For an overview, see 'git help git'.\n\nI am neutral between the above and this:\n\n For an overview, see 'git help git'.\n 'git help -a' and 'git help -g' lists available subcommands and\n concept guides. See 'git help ' or 'git help '\n to read about a specific subcommand or concept.\n\nHrm?\n"}]}