[PATCH/RFC] Make help behaviour more consistent

[PATCH/RFC] Make help behaviour more consistent

[Kevin Bracey]

Previously, the command "help" and the option "-h" behaved differently
depending on whether a command was specified or not. Old user interface:

Commands with no defaults show usage: "git"           "git CMD"
To specifically request usage:        "git help"      "git CMD -h"
To get a manual page:                 "git help git"  "git help CMD"

Two significant usability flaws here:
 - If using man, "man git" to side-step "git help" is obvious. But if
   trying to use help.format=web, how to get the root html page? My
   technique was "git help XXX" and click the "git(1) suite" link at the
   bottom. "git help git" is non-obvious and apparently undocumented
   (it's not mentioned by "git", "git help", or "git help help"...).

 - Because git itself didn't support -h (and thus actually printed less
   if you specified it), the general availability of -h for commands was
   non-obvious. I didn't know about it until I started this patch.

Tidy this up, so that help and -h do not change behaviour depending on
whether a command is specified or not. New, consistent user interface:

Commands with no defaults show usage: "git"           "git CMD"
To specifically request usage:        "git -h"        "git CMD -h"
To get a manual page:                 "git help"      "git help CMD".

"git help git" is still accepted. The legacy "--help" option behaves as
before, which means "git --help" on its own is now a synonym for "git
-h", not "git help", and it remains consistent with GNU Coding
Guidelines.

So the only change to existing command behaviour is that "git help" or
"git help -w" now opens the git manual page, rather than showing common
commands.

"git -h cmd" is also accepted as a synonym for "git cmd -h", as per
Linus's rationale for treating "git cmd --help" as a synonym for "git
--help cmd".

Option list shown in command-line usage re-ordered to match the manual
page, and git and git-help manual pages edited to reflect the new help
behaviour.

Signed-off-by: Kevin Bracey <kevin@bracey.fi>
---
 Documentation/git-help.txt | 22 +++++++++-------------
 Documentation/git.txt      | 17 ++++++++---------
 builtin/help.c             |  9 +--------
 git.c                      | 40 +++++++++++++++++++++++-----------------
 4 files changed, 41 insertions(+), 47 deletions(-)

diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index e07b6dc..25def9f 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -13,19 +13,16 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-With no options and no COMMAND given, the synopsis of the 'git'
-command and a list of the most commonly used Git commands are printed
-on the standard output.
-
 If the option '--all' or '-a' is given, then all available commands are
 printed on the standard output.
 
-If a Git subcommand is named, a manual page for that subcommand is brought
+Otherwise, a manual page for Git or the specified Git command is brought
 up. The 'man' program is used by default for this purpose, but this
 can be overridden by other options or configuration variables.
 
 Note that `git --help ...` is identical to `git help ...` because the
-former is internally converted into the latter.
+former is internally converted into the latter.  Also, to supplement
+`git help`, most Git commands offer the option '-h' to print usage.
 
 OPTIONS
 -------
@@ -36,14 +33,13 @@ OPTIONS
 
 -i::
 --info::
-	Display manual page for the command in the 'info' format. The
-	'info' program will be used for that purpose.
+	Display manual page in the 'info' format. The 'info' program will
+	be used for that purpose.
 
 -m::
 --man::
-	Display manual page for the command in the 'man' format. This
-	option may be used to override a value set in the
-	'help.format' configuration variable.
+	Display manual page in the 'man' format. This option may be used to
+	override a value set in the 'help.format' configuration variable.
 +
 By default the 'man' program will be used to display the manual page,
 but the 'man.viewer' configuration variable may be used to choose
@@ -51,8 +47,8 @@ other display programs (see below).
 
 -w::
 --web::
-	Display manual page for the command in the 'web' (HTML)
-	format. A web browser will be used for that purpose.
+	Display manual page in the 'web' (HTML)	format. A web browser will
+	be used for that purpose.
 +
 The web browser can be specified using the configuration variable
 'help.browser', or 'web.browser' if the former is not set. If none of
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 9d29ed5..51cdca2 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -9,7 +9,7 @@ git - the stupid content tracker
 SYNOPSIS
 --------
 [verse]
-'git' [--version] [--help] [-c <name>=<value>]
+'git' [--version] [--help] [-h] [-c <name>=<value>]
     [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
     [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
     [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
@@ -361,16 +361,15 @@ OPTIONS
 --version::
 	Prints the Git suite version that the 'git' program came from.
 
---help::
+-h::
 	Prints the synopsis and a list of the most commonly used
-	commands. If the option '--all' or '-a' is given then all
-	available commands are printed. If a Git command is named this
-	option will bring up the manual page for that command.
+	commands. Most Git commands also provide a '-h'	option to
+	show their own synopsis.
 +
-Other options are available to control how the manual page is
-displayed. See linkgit:git-help[1] for more information,
-because `git --help ...` is converted internally into `git
-help ...`.
+For compatibility, `git --help` is also implemented. With no
+following options, it is equivalent to `git -h`. Otherwise it is
+converted internally into `git help ...`, which will open a manual
+page. See linkgit:git-help[1] for more information.
 
 -c <name>=<value>::
 	Pass a configuration parameter to the command. The value
diff --git a/builtin/help.c b/builtin/help.c
index d1d7181..ef4706a 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -432,13 +432,6 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		return 0;
 	}
 
-	if (!argv[0]) {
-		printf(_("usage: %s%s"), _(git_usage_string), "\n\n");
-		list_common_cmds_help();
-		printf("\n%s\n", _(git_more_info_string));
-		return 0;
-	}
-
 	setup_git_directory_gently(&nongit);
 	git_config(git_help_config, NULL);
 
@@ -447,7 +440,7 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 	if (help_format == HELP_FORMAT_NONE)
 		help_format = parse_help_format(DEFAULT_HELP_FORMAT);
 
-	alias = alias_lookup(argv[0]);
+	alias = argv[0] ? alias_lookup(argv[0]) : NULL;
 	if (alias && !is_git_command(argv[0])) {
 		printf_ln(_("`git %s' is aliased to `%s'"), argv[0], alias);
 		return 0;
diff --git a/git.c b/git.c
index b10c18b..82a74c5 100644
--- a/git.c
+++ b/git.c
@@ -6,10 +6,10 @@
 #include "run-command.h"
 
 const char git_usage_string[] =
-	"git [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]\n"
+	"git [--version] [--help] [-h] [-c name=value]\n"
+	"           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]\n"
 	"           [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]\n"
 	"           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]\n"
-	"           [-c name=value] [--help]\n"
 	"           <command> [<args>]";
 
 const char git_more_info_string[] =
@@ -17,6 +17,7 @@ const char git_more_info_string[] =
 
 static struct startup_info git_startup_info;
 static int use_pager = -1;
+static int show_usage;
 
 static void commit_pager_choice(void) {
 	switch (use_pager) {
@@ -40,17 +41,6 @@ static int handle_options(const char ***argv, int *argc, int *envchanged)
 		if (cmd[0] != '-')
 			break;
 
-		/*
-		 * For legacy reasons, the "version" and "help"
-		 * commands can be written with "--" prepended
-		 * to make them look like flags.
-		 */
-		if (!strcmp(cmd, "--help") || !strcmp(cmd, "--version"))
-			break;
-
-		/*
-		 * Check remaining flags.
-		 */
 		if (!prefixcmp(cmd, "--exec-path")) {
 			cmd += 11;
 			if (*cmd == '=')
@@ -143,6 +133,25 @@ static int handle_options(const char ***argv, int *argc, int *envchanged)
 			setenv(GIT_LITERAL_PATHSPECS_ENVIRONMENT, "0", 1);
 			if (envchanged)
 				*envchanged = 1;
+		} else if (!strcmp(cmd, "--version")) {
+			/* Alternative spelling for "git version" */
+			(*argv)[0] += 2;
+			break;
+		} else if (!strcmp(cmd, "--help")) {
+			if (*argc > 1) {
+				/* Alternative spelling for "git help XXX" */
+				(*argv)[0] += 2;
+				break;
+			} else
+				show_usage = 1;
+		} else if (!strcmp(cmd, "-h")) {
+			if (*argc > 1 && (*argv)[1][0] != '-') {
+				/* Turn "git -h cmd" into "git cmd -h" */
+				(*argv)[0] = (*argv)[1];
+				(*argv)[1] = "-h";
+				break;
+			} else
+				show_usage = 1;
 		} else {
 			fprintf(stderr, "Unknown option: %s\n", cmd);
 			usage(git_usage_string);
@@ -537,10 +546,7 @@ int main(int argc, const char **argv)
 	argv++;
 	argc--;
 	handle_options(&argv, &argc, NULL);
-	if (argc > 0) {
-		if (!prefixcmp(argv[0], "--"))
-			argv[0] += 2;
-	} else {
+	if (argc <= 0 || show_usage) {
 		/* The user didn't specify a command; give them help */
 		commit_pager_choice();
 		printf("usage: %s\n\n", git_usage_string);
-- 
1.8.2.rc3.7.g1100d09.dirty

Re: [PATCH/RFC] Make help behaviour more consistent

[Philip Oakley]

On 10/03/13 17:48, Kevin Bracey wrote:
> Previously, the command "help" and the option "-h" behaved differently
> depending on whether a command was specified or not. Old user interface:
>
> Commands with no defaults show usage: "git"           "git CMD"
> To specifically request usage:        "git help"      "git CMD -h"
> To get a manual page:                 "git help git"  "git help CMD"
>

I agree they were inconsistent, but the change should also consider how 
the help for 'git help' should be provided as well.

I have some patches in preparation for also listing the commonly used 
guides, which can also be accessed by the existing `git help <guide>` 
e.g. 'tutorial' (but not user-manual or everday git unfortunately).

http://permalink.gmane.org/gmane.comp.version-control.git/217354

I have a new version in prep but my ubuntu m/c is out of action.

> Two significant usability flaws here:
>   - If using man, "man git" to side-step "git help" is obvious. But if
>     trying to use help.format=web, how to get the root html page? My
>     technique was "git help XXX" and click the "git(1) suite" link at the
>     bottom. "git help git" is non-obvious and apparently undocumented
>     (it's not mentioned by "git", "git help", or "git help help"...).
>
>   - Because git itself didn't support -h (and thus actually printed less
>     if you specified it), the general availability of -h for commands was
>     non-obvious. I didn't know about it until I started this patch.
>
> Tidy this up, so that help and -h do not change behaviour depending on
> whether a command is specified or not. New, consistent user interface:
>
> Commands with no defaults show usage: "git"           "git CMD"
> To specifically request usage:        "git -h"        "git CMD -h"
> To get a manual page:                 "git help"      "git help CMD".
>
> "git help git" is still accepted. The legacy "--help" option behaves as
> before, which means "git --help" on its own is now a synonym for "git
> -h", not "git help", and it remains consistent with GNU Coding
> Guidelines.
>
> So the only change to existing command behaviour is that "git help" or
> "git help -w" now opens the git manual page, rather than showing common
> commands.
>
> "git -h cmd" is also accepted as a synonym for "git cmd -h", as per
> Linus's rationale for treating "git cmd --help" as a synonym for "git
> --help cmd".
>
> Option list shown in command-line usage re-ordered to match the manual
> page, and git and git-help manual pages edited to reflect the new help
> behaviour.
>
> Signed-off-by: Kevin Bracey <kevin@bracey.fi>
> ---
>   Documentation/git-help.txt | 22 +++++++++-------------
>   Documentation/git.txt      | 17 ++++++++---------
>   builtin/help.c             |  9 +--------
>   git.c                      | 40 +++++++++++++++++++++++-----------------
>   4 files changed, 41 insertions(+), 47 deletions(-)
>
> diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
> index e07b6dc..25def9f 100644
> --- a/Documentation/git-help.txt
> +++ b/Documentation/git-help.txt
> @@ -13,19 +13,16 @@ SYNOPSIS
>   DESCRIPTION
>   -----------
>
> -With no options and no COMMAND given, the synopsis of the 'git'
> -command and a list of the most commonly used Git commands are printed
> -on the standard output.
> -
>   If the option '--all' or '-a' is given, then all available commands are
>   printed on the standard output.
>
> -If a Git subcommand is named, a manual page for that subcommand is brought
> +Otherwise, a manual page for Git or the specified Git command is brought
>   up. The 'man' program is used by default for this purpose, but this
>   can be overridden by other options or configuration variables.
>
>   Note that `git --help ...` is identical to `git help ...` because the
> -former is internally converted into the latter.
> +former is internally converted into the latter.  Also, to supplement
> +`git help`, most Git commands offer the option '-h' to print usage.
>
>   OPTIONS
>   -------
> @@ -36,14 +33,13 @@ OPTIONS
>
>   -i::
>   --info::
> -	Display manual page for the command in the 'info' format. The
> -	'info' program will be used for that purpose.
> +	Display manual page in the 'info' format. The 'info' program will
> +	be used for that purpose.
>
>   -m::
>   --man::
> -	Display manual page for the command in the 'man' format. This
> -	option may be used to override a value set in the
> -	'help.format' configuration variable.
> +	Display manual page in the 'man' format. This option may be used to
> +	override a value set in the 'help.format' configuration variable.
>   +
>   By default the 'man' program will be used to display the manual page,
>   but the 'man.viewer' configuration variable may be used to choose
> @@ -51,8 +47,8 @@ other display programs (see below).
>
>   -w::
>   --web::
> -	Display manual page for the command in the 'web' (HTML)
> -	format. A web browser will be used for that purpose.
> +	Display manual page in the 'web' (HTML)	format. A web browser will
> +	be used for that purpose.
>   +
>   The web browser can be specified using the configuration variable
>   'help.browser', or 'web.browser' if the former is not set. If none of
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 9d29ed5..51cdca2 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -9,7 +9,7 @@ git - the stupid content tracker
>   SYNOPSIS
>   --------
>   [verse]
> -'git' [--version] [--help] [-c <name>=<value>]
> +'git' [--version] [--help] [-h] [-c <name>=<value>]
>       [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
>       [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
>       [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
> @@ -361,16 +361,15 @@ OPTIONS
>   --version::
>   	Prints the Git suite version that the 'git' program came from.
>
> ---help::
> +-h::
>   	Prints the synopsis and a list of the most commonly used
> -	commands. If the option '--all' or '-a' is given then all
> -	available commands are printed. If a Git command is named this
> -	option will bring up the manual page for that command.
> +	commands. Most Git commands also provide a '-h'	option to
> +	show their own synopsis.
>   +
> -Other options are available to control how the manual page is
> -displayed. See linkgit:git-help[1] for more information,
> -because `git --help ...` is converted internally into `git
> -help ...`.
> +For compatibility, `git --help` is also implemented. With no
> +following options, it is equivalent to `git -h`. Otherwise it is
> +converted internally into `git help ...`, which will open a manual
> +page. See linkgit:git-help[1] for more information.
>
>   -c <name>=<value>::
>   	Pass a configuration parameter to the command. The value
> diff --git a/builtin/help.c b/builtin/help.c
> index d1d7181..ef4706a 100644
> --- a/builtin/help.c
> +++ b/builtin/help.c
> @@ -432,13 +432,6 @@ int cmd_help(int argc, const char **argv, const char *prefix)
>   		return 0;
>   	}
>
> -	if (!argv[0]) {
> -		printf(_("usage: %s%s"), _(git_usage_string), "\n\n");
> -		list_common_cmds_help();
> -		printf("\n%s\n", _(git_more_info_string));
> -		return 0;
> -	}
> -
>   	setup_git_directory_gently(&nongit);
>   	git_config(git_help_config, NULL);
>
> @@ -447,7 +440,7 @@ int cmd_help(int argc, const char **argv, const char *prefix)
>   	if (help_format == HELP_FORMAT_NONE)
>   		help_format = parse_help_format(DEFAULT_HELP_FORMAT);
>
> -	alias = alias_lookup(argv[0]);
> +	alias = argv[0] ? alias_lookup(argv[0]) : NULL;
>   	if (alias && !is_git_command(argv[0])) {
>   		printf_ln(_("`git %s' is aliased to `%s'"), argv[0], alias);
>   		return 0;
> diff --git a/git.c b/git.c
> index b10c18b..82a74c5 100644
> --- a/git.c
> +++ b/git.c
> @@ -6,10 +6,10 @@
>   #include "run-command.h"
>
>   const char git_usage_string[] =
> -	"git [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]\n"
> +	"git [--version] [--help] [-h] [-c name=value]\n"
> +	"           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]\n"
>   	"           [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]\n"
>   	"           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]\n"
> -	"           [-c name=value] [--help]\n"
>   	"           <command> [<args>]";
>
>   const char git_more_info_string[] =
> @@ -17,6 +17,7 @@ const char git_more_info_string[] =
>
>   static struct startup_info git_startup_info;
>   static int use_pager = -1;
> +static int show_usage;
>
>   static void commit_pager_choice(void) {
>   	switch (use_pager) {
> @@ -40,17 +41,6 @@ static int handle_options(const char ***argv, int *argc, int *envchanged)
>   		if (cmd[0] != '-')
>   			break;
>
> -		/*
> -		 * For legacy reasons, the "version" and "help"
> -		 * commands can be written with "--" prepended
> -		 * to make them look like flags.
> -		 */
> -		if (!strcmp(cmd, "--help") || !strcmp(cmd, "--version"))
> -			break;
> -
> -		/*
> -		 * Check remaining flags.
> -		 */
>   		if (!prefixcmp(cmd, "--exec-path")) {
>   			cmd += 11;
>   			if (*cmd == '=')
> @@ -143,6 +133,25 @@ static int handle_options(const char ***argv, int *argc, int *envchanged)
>   			setenv(GIT_LITERAL_PATHSPECS_ENVIRONMENT, "0", 1);
>   			if (envchanged)
>   				*envchanged = 1;
> +		} else if (!strcmp(cmd, "--version")) {
> +			/* Alternative spelling for "git version" */
> +			(*argv)[0] += 2;
> +			break;
> +		} else if (!strcmp(cmd, "--help")) {
> +			if (*argc > 1) {
> +				/* Alternative spelling for "git help XXX" */
> +				(*argv)[0] += 2;
> +				break;
> +			} else
> +				show_usage = 1;
> +		} else if (!strcmp(cmd, "-h")) {
> +			if (*argc > 1 && (*argv)[1][0] != '-') {
> +				/* Turn "git -h cmd" into "git cmd -h" */
> +				(*argv)[0] = (*argv)[1];
> +				(*argv)[1] = "-h";
> +				break;
> +			} else
> +				show_usage = 1;
>   		} else {
>   			fprintf(stderr, "Unknown option: %s\n", cmd);
>   			usage(git_usage_string);
> @@ -537,10 +546,7 @@ int main(int argc, const char **argv)
>   	argv++;
>   	argc--;
>   	handle_options(&argv, &argc, NULL);
> -	if (argc > 0) {
> -		if (!prefixcmp(argv[0], "--"))
> -			argv[0] += 2;
> -	} else {
> +	if (argc <= 0 || show_usage) {
>   		/* The user didn't specify a command; give them help */
>   		commit_pager_choice();
>   		printf("usage: %s\n\n", git_usage_string);
>

Re: [PATCH/RFC] Make help behaviour more consistent

[Junio C Hamano]

Kevin Bracey <kevin@bracey.fi> writes:

> Previously, the command "help" and the option "-h" behaved differently
> depending on whether a command was specified or not. Old user interface:
>
> Commands with no defaults show usage: "git"           "git CMD"
> To specifically request usage:        "git help"      "git CMD -h"
> To get a manual page:                 "git help git"  "git help CMD"
>
> Two significant usability flaws here:
>  - If using man, "man git" to side-step "git help" is obvious. But if
>    trying to use help.format=web, how to get the root html page? My
>    technique was "git help XXX" and click the "git(1) suite" link at the
>    bottom. "git help git" is non-obvious and apparently undocumented
>    (it's not mentioned by "git", "git help", or "git help help"...).
>
>  - Because git itself didn't support -h (and thus actually printed less
>    if you specified it), the general availability of -h for commands was
>    non-obvious. I didn't know about it until I started this patch.

Hmm, I feel more confused than convinced after reading the above
three times.  Perhaps that is because I am too used to the way how
"git" potty itself behaves, especially the part that "git help git"
is the way to ask "git" (the first token on the command line) to
give me "help" about "git" (the second) itself.

Having said that, I would agree that "git -h" that shows a "unknown
option" error message that lists the supported command line options
(just like how it reacts to "git -x") is less friendly than "git"
that knows "-h" to show the short help text, and that part of the
patch is a definite improvement.  But other than that I do not see
any "significant usablity flow" in it.

The patch seems to do a lot more than just teaching "git" to react
to "-h" to give a short usage, instead of doing the generic "I do
not know -h option" thing.  I am not sure what merit these other
changes of this patch have.

In the introductory part, you list three possibilities, but there is
the fourth "git help help" to ask "git" to give me "help" about
"help".  Depending on where one comes from, that may also seem just
as odd as "git help git" (again, I personally find neither is odd,
though). Would this change help with that "usability flaw" as well?

Undecided...

Re: [PATCH/RFC] Make help behaviour more consistent

[Matthieu Moy]

Kevin Bracey <kevin@bracey.fi> writes:

> Two significant usability flaws here:
>  - If using man, "man git" to side-step "git help" is obvious. But if
>    trying to use help.format=web, how to get the root html page? My
>    technique was "git help XXX" and click the "git(1) suite" link at the
>    bottom. "git help git" is non-obvious and apparently undocumented
>    (it's not mentioned by "git", "git help", or "git help help"...).

Can't this be solved by adding something like

  See 'git help git' for general help about Git.

to the output of "git help"? I think the fact that "git help" provides a
small amount of output (typically: fits on one screen) is a nice feature
that avoids scaring people too early with the actual doc.

That said, I'm no longer a user of the short command list, so maybe I'm
not a good judge ;-).

> Option list shown in command-line usage re-ordered to match the manual
> page, and git and git-help manual pages edited to reflect the new help
> behaviour.

This is typically better submitted as a separate patch. Putting
uncontroversial changes in their own patches help the discussion to
focus on important changes, and avoids distracting the review.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH/RFC] Make help behaviour more consistent

[Kevin Bracey]

On 11/03/2013 05:03, Junio C Hamano wrote:
> Hmm, I feel more confused than convinced after reading the above
> three times.  Perhaps that is because I am too used to the way how
> "git" potty itself behaves, especially the part that "git help git"
> is the way to ask "git" (the first token on the command line) to
> give me "help" about "git" (the second) itself.

But you are nowhere told that "git help" will give you information on 
any topic other than Git commands. Starting from just typing "git", all 
you are told is that you can type "git help <command>". Given that 
information, you could at least logically deduce that "git help help" 
will give you help on "git help". (Not that it would help anyway - even 
git-help.txt doesn't say that you can specify anything other than a Git 
command, like "git" or "cli". But sounds like Philip's already on there 
case there).

If you can figure out "man git" for yourself (and if it's available - 
Windows?) then from there you're explicitly told how to directly access 
all the other docs using man itself, including gitrevisions(7), etc.

And having gotten to "man gitrevisions", I figured out that "git help 
revisions" could get to the HTML equivalent. Not documented, but at 
least fits the pattern, give or take a hyphen.  But I never figured out 
"git help git", until I read the source. Why do I need to add the extra 
"git" to the help command for that page, and that page only? "git" isn't 
a Git command, and there's no "man gitgit" topic! Even if I explicitly 
try to point explicitly that I want a web page with "git help -w", I 
don't get it...

I think at the very minimum you need to make it explicitly clear right 
up front that "git help git" is available:

    See 'git help git' for more information on Git
See 'git help <command>' for more information on a specific command.

Seems ugly though. I'm at a loss to understand why "git help", the 
manual launching command, shouldn't by default simply launch the root of 
the manual tree, rather than replicate the behaviour of "git"/"git --help".

And something needs to be done to advertise the general existence of 
usage on commands. "-h" is currently hidden on page 4 of "man gitcli". 
(Is it anywhere else?)  I've managed to avoid finding out about it for 
years! Checking a few people around me, none of them knew about it either.

At the minute "git" tells you about "git --help", which shows usage, but 
"git add --help" launches the manual. (Huh?) Given that, I always 
assumed there was no usage available for individual commands - if there 
was usage, surely it would be there on --help, like on "git". Never 
occurred to me it would be there under "-h" instead.

So how about going further than that patch, and making it even simpler. 
Collapse --help and -h to be synonyms. Then under either spelling, 
--help|-h always shows usage for "git" or "git <command>", as per GNU 
guidelines.

Then the manual launch only happens for "git help ..." and, "git help" 
on its own launches the root. And the output of "git [--help]" ends with:

    See 'git help [<command>]' for more information.

Kevin

Re: [PATCH/RFC] Make help behaviour more consistent

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> Kevin Bracey <kevin@bracey.fi> writes:
>
>> Two significant usability flaws here:
>>  - If using man, "man git" to side-step "git help" is obvious. But if
>>    trying to use help.format=web, how to get the root html page? My
>>    technique was "git help XXX" and click the "git(1) suite" link at the
>>    bottom. "git help git" is non-obvious and apparently undocumented
>>    (it's not mentioned by "git", "git help", or "git help help"...).
>
> Can't this be solved by adding something like
>
>   See 'git help git' for general help about Git.
>
> to the output of "git help"? I think the fact that "git help" provides a
> small amount of output (typically: fits on one screen) is a nice feature
> that avoids scaring people too early with the actual doc.

That sounds like a good direction to go in.

Re: [PATCH/RFC] Make help behaviour more consistent

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Monday, March 11, 2013 7:02 PM
> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
>
>> Kevin Bracey <kevin@bracey.fi> writes:
>>
>>> Two significant usability flaws here:
>>>  - If using man, "man git" to side-step "git help" is obvious. But 
>>> if
>>>    trying to use help.format=web, how to get the root html page? My
>>>    technique was "git help XXX" and click the "git(1) suite" link at 
>>> the
>>>    bottom. "git help git" is non-obvious and apparently undocumented
>>>    (it's not mentioned by "git", "git help", or "git help help"...).
>>
>> Can't this be solved by adding something like
>>
>>   See 'git help git' for general help about Git.
>>
>> to the output of "git help"? I think the fact that "git help" 
>> provides a
>> small amount of output (typically: fits on one screen) is a nice 
>> feature
>> that avoids scaring people too early with the actual doc.
>
> That sounds like a good direction to go in.

My earlier attempt, and Junio's reply 
http://thread.gmane.org/gmane.comp.version-control.git/217352

It is tricky making sure that the message covers help for git, help's 
own help,
the guides, and the commands, all in one compact usage line, while also
covering the -h and --help options (which may not be known to new Git
users on Windows, though probably obvious to Linux/Unix users).

Philip 

Re: [PATCH/RFC] Make help behaviour more consistent

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> From: "Junio C Hamano" <gitster@pobox.com>
>> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
>>
>>>   See 'git help git' for general help about Git.
>>>
>>> to the output of "git help"?
>> ...
>> That sounds like a good direction to go in.
>
> My earlier attempt, and Junio's reply
> http://thread.gmane.org/gmane.comp.version-control.git/217352

Yeah, I threw "git help git" in the general category of "git help
<cmd>" in that message, and now I realize that it may arguably be
confusing to some people.

Perhaps spend one more line to do something like this?

    'git help -a' and 'git help -g' lists available subcommands and
    concept guides. See 'git help <command>' or 'git help <concept>'
    to read about a specific subcommand or concept.
    For an overview, see 'git help git'.

I am neutral between the above and this:

    For an overview, see 'git help git'.
    'git help -a' and 'git help -g' lists available subcommands and
    concept guides. See 'git help <command>' or 'git help <concept>'
    to read about a specific subcommand or concept.

Hrm?