[PATCH/RFC] Make help behaviour more consistent

[Kevin Bracey <kevin@bracey.fi>]

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