[PATCH v2 0/5] [RESEND with Cc:] Git help option to list user guides

[PATCH v2 0/5] [RESEND with Cc:] Git help option to list user guides

[Philip Oakley]

This is the much truncated (was 0/13] and updated series for
noting that 'git help' can display the existing guides that are
formatted as man pages, and providing a 'git help' option to list
a few of the most useful guides.

The series is rebased on top of V1.8.2-rc1

Differences relative to V1 numbering
Patch 1: Use 'Git' in help messages
Dropped.
a. the 'git version' string is used in the wild for version checking,
in particular Git Gui checks the string is 'git version'.
b. a recent patch series fixed on lower case messages for 'usage:',
respect that.
c. many consider that the 'git' reference was to the 'git <cmd>' format
rather than (the system) Git's commands.

Patch 2 (now 1/5): Show 'git help <guide>' usage, with examples
Correct elipsis dots for unterminated list of examples.

Patch 2 (now 2/5): Help.c use OPT_COUNTUP
Unchanged.

Patch 4 (now 3/5): Help.c add --guide option
Update commit message to explain the -g|--guide logic.

Patch 5 (now 4/5): Help.c: add list_common_guides_help() function
Removed the 'build artefact' /* */ comment line.
Note that these are just the common guides and used in a usage message.
The data was generated by a script variant of generate-cmdlist.sh

Patch (new 5/5): Help doc: Include --guide option description
Update the documentation/git-help.txt - I had been caught out by
the same 'focus on the code' mistake made by many and forgot
the documenation ;-)

Patch 6 - 13: 
All dropped.
Drop the separate guide list.txt and extraction script, which was
copied from the common command list and script. If the guide usage
list is useful, extend the command-list.txt and generate-cmdlist.sh
at a later date.

Drop the rename of user-manual and everyday because they are not
formatted as manuals. They can't be started by help's call to 'man'
(and possibly other paths) anyway.

Philip Oakley (5):
  Show 'git help <guide>' usage, with examples
  Help.c use OPT_COUNTUP
  Help.c add --guide option
  Help.c: add list_common_guides_help() function
  Help doc: Include --guide option description

 Documentation/git-help.txt | 28 +++++++++++++++++++++-------
 builtin/help.c             | 11 ++++++++---
 common-guides.h            | 11 +++++++++++
 git.c                      |  4 +++-
 help.c                     | 18 ++++++++++++++++++
 help.h                     |  1 +
 6 files changed, 62 insertions(+), 11 deletions(-)
 create mode 100644 common-guides.h

-- 
1.8.1.msysgit.1

[PATCH v2 1/5] Show 'git help <guide>' usage, with examples

[Philip Oakley]

The git(1) man page must be accessed via 'git help git' on Git for Windows
as it has no 'man' command. And it prompts users to read the git(1) page,
rather than hoping they follow a subsidiary link within another
documentation page. The 'tutorial' is an obvious guide to suggest.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 git.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/git.c b/git.c
index b10c18b..d9b71c1 100644
--- a/git.c
+++ b/git.c
@@ -13,7 +13,9 @@ const char git_usage_string[] =
 	"           <command> [<args>]";
 
 const char git_more_info_string[] =
-	N_("See 'git help <command>' for more information on a specific command.");
+	N_("See 'git help <command>' for more information on a specific command.\n"
+	   "While 'git help <guide>', will show the selected Git concept guide.\n"
+	   "Examples: 'git help git', 'git help branch', 'git help tutorial'...");
 
 static struct startup_info git_startup_info;
 static int use_pager = -1;
-- 
1.8.1.msysgit.1

[PATCH v2 2/5] Help.c use OPT_COUNTUP

[Philip Oakley]

rename deprecated option in preparation for 'git help --guides'.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 builtin/help.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/builtin/help.c b/builtin/help.c
index d1d7181..d10cbed 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -39,7 +39,7 @@ static int show_all = 0;
 static unsigned int colopts;
 static enum help_format help_format = HELP_FORMAT_NONE;
 static struct option builtin_help_options[] = {
-	OPT_BOOLEAN('a', "all", &show_all, N_("print all available commands")),
+	OPT_COUNTUP('a', "all", &show_all, N_("print all available commands")),
 	OPT_SET_INT('m', "man", &help_format, N_("show man page"), HELP_FORMAT_MAN),
 	OPT_SET_INT('w', "web", &help_format, N_("show manual in web browser"),
 			HELP_FORMAT_WEB),
-- 
1.8.1.msysgit.1

[PATCH v2 3/5] Help.c add --guide option

[Philip Oakley]

Logic, but no actions, included.

The --all commands option, if given, will display first.
The --guide option's list will then be displayed.

The common commands list is only displayed if neither option,
nor a command or guide name, is given.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 builtin/help.c | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/builtin/help.c b/builtin/help.c
index d10cbed..6089d72 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -36,10 +36,12 @@ enum help_format {
 static const char *html_path;
 
 static int show_all = 0;
+static int show_guides = 0;
 static unsigned int colopts;
 static enum help_format help_format = HELP_FORMAT_NONE;
 static struct option builtin_help_options[] = {
 	OPT_COUNTUP('a', "all", &show_all, N_("print all available commands")),
+	OPT_COUNTUP('g', "guides", &show_guides, N_("print list of useful guides")),
 	OPT_SET_INT('m', "man", &help_format, N_("show man page"), HELP_FORMAT_MAN),
 	OPT_SET_INT('w', "web", &help_format, N_("show manual in web browser"),
 			HELP_FORMAT_WEB),
@@ -49,7 +51,7 @@ static struct option builtin_help_options[] = {
 };
 
 static const char * const builtin_help_usage[] = {
-	N_("git help [--all] [--man|--web|--info] [command]"),
+	N_("git help [--all] [--guides] [--man|--web|--info] [command]"),
 	NULL
 };
 
@@ -429,9 +431,11 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		printf(_("usage: %s%s"), _(git_usage_string), "\n\n");
 		list_commands(colopts, &main_cmds, &other_cmds);
 		printf("%s\n", _(git_more_info_string));
+		if (!show_guides) return 0;
+	}
+	if (show_guides) {
 		return 0;
 	}
-
 	if (!argv[0]) {
 		printf(_("usage: %s%s"), _(git_usage_string), "\n\n");
 		list_common_cmds_help();
-- 
1.8.1.msysgit.1

[PATCH v2 4/5] Help.c: add list_common_guides_help() function

[Philip Oakley]

Re-use list_common_cmds_help but simply change the array name.
Candidate for future refactoring to pass a pointer to the array.

The common-guides.h list was generated with a simple variant of the
generate-cmdlist.sh and command-list.txt.

Do not list User-manual and Everday Git which not follow the naming
convention, nor gitrepository-layout which doesn't fit within the
name field size.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 builtin/help.c  |  1 +
 common-guides.h | 11 +++++++++++
 help.c          | 18 ++++++++++++++++++
 help.h          |  1 +
 4 files changed, 31 insertions(+)
 create mode 100644 common-guides.h

diff --git a/builtin/help.c b/builtin/help.c
index 6089d72..e21ffa5 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -434,6 +434,7 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		if (!show_guides) return 0;
 	}
 	if (show_guides) {
+		list_common_guides_help();
 		return 0;
 	}
 	if (!argv[0]) {
diff --git a/common-guides.h b/common-guides.h
new file mode 100644
index 0000000..0e94fdc
--- /dev/null
+++ b/common-guides.h
@@ -0,0 +1,11 @@
+/* re-use struct cmdname_help in common-commands.h */
+
+static struct cmdname_help common_guides[] = {
+  {"attributes", "defining attributes per path"},
+  {"glossary", "A GIT Glossary"},
+  {"ignore", "Specifies intentionally untracked files to ignore"},
+  {"modules", "defining submodule properties"},
+  {"revisions", "specifying revisions and ranges for git"},
+  {"tutorial", "A tutorial introduction to git (for version 1.5.1 or newer)"},
+  {"workflows", "An overview of recommended workflows with git"},
+};
diff --git a/help.c b/help.c
index 1dfa0b0..f4de407 100644
--- a/help.c
+++ b/help.c
@@ -4,6 +4,7 @@
 #include "levenshtein.h"
 #include "help.h"
 #include "common-cmds.h"
+#include "common-guides.h"
 #include "string-list.h"
 #include "column.h"
 #include "version.h"
@@ -240,6 +241,23 @@ void list_common_cmds_help(void)
 	}
 }
 
+void list_common_guides_help(void)
+{
+	int i, longest = 0;
+
+	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
+		if (longest < strlen(common_guides[i].name))
+			longest = strlen(common_guides[i].name);
+	}
+
+	puts(_("The common Git guides are:"));
+	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
+		printf("   %s   ", common_guides[i].name);
+		mput_char(' ', longest - strlen(common_guides[i].name));
+		puts(_(common_guides[i].help));
+	}
+}
+
 int is_in_cmdlist(struct cmdnames *c, const char *s)
 {
 	int i;
diff --git a/help.h b/help.h
index 0ae5a12..4ae1fd7 100644
--- a/help.h
+++ b/help.h
@@ -17,6 +17,7 @@ static inline void mput_char(char c, unsigned int num)
 }
 
 extern void list_common_cmds_help(void);
+extern void list_common_guides_help(void);
 extern const char *help_unknown_cmd(const char *cmd);
 extern void load_command_list(const char *prefix,
 			      struct cmdnames *main_cmds,
-- 
1.8.1.msysgit.1

[PATCH v2 5/5] Help doc: Include --guide option description

[Philip Oakley]

Note that the ability to display an individual guide was
always possible. Include this in the update.

Also tell readers how git(1) can be accessed, especially for
Git for Windows users who do not have the 'man' command.
Likewise include a commentary on how to access this page (Catch 22).

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/git-help.txt | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index e07b6dc..498a94e 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -8,31 +8,45 @@ git-help - Display help information about Git
 SYNOPSIS
 --------
 [verse]
-'git help' [-a|--all|-i|--info|-m|--man|-w|--web] [COMMAND]
+'git help' [-a|--all] [-g|--guide]
+	   [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE]
 
 DESCRIPTION
 -----------
 
-With no options and no COMMAND given, the synopsis of the 'git'
+With no options and no COMMAND|GUIDE 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
-up. The 'man' program is used by default for this purpose, but this
-can be overridden by other options or configuration variables.
+If the option '--guide' or '-g' is given then, a list of the useful
+Git guides is also printed on the standard output.
 
-Note that `git --help ...` is identical to `git help ...` because the
+If a Git subcommand, or a Git guide, is given, a manual page for that
+subcommand 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.
 
+To display the linkgit:git[1] man page use 'git help git'.
+
+This page can be displayed with 'git help help' or 'git help --help'
+
 OPTIONS
 -------
 -a::
 --all::
 	Prints all the available commands on the standard output. This
-	option supersedes any other option.
+	option overides any given command or guide name.
+
+-g::
+--guides::
+	Prints a list of useful guides on the standard output. This
+	option overides any given command or guide name.
 
 -i::
 --info::
-- 
1.8.1.msysgit.1

[PATCH v2 0/5] Git help option to list user guides

[Philip Oakley]

This is the much truncated (was 0/13] and updated series for
noting that 'git help' can display the existing guides that are
formatted as man pages, and providing a 'git help' option to list
a few of the most useful guides.

The series is rebased on top of V1.8.2-rc1

Differences relative to V1 numbering
Patch 1: Use 'Git' in help messages
Dropped.
a. the 'git version' string is used in the wild for version checking,
in particular Git Gui checks the string is 'git version'.
b. a recent patch series fixed on lower case messages for 'usage:',
respect that.
c. many consider that the 'git' reference was to the 'git <cmd>' format
rather than (the system) Git's commands.

Patch 2 (now 1/5): Show 'git help <guide>' usage, with examples
Correct elipsis dots for unterminated list of examples.

Patch 2 (now 2/5): Help.c use OPT_COUNTUP
Unchanged.

Patch 4 (now 3/5): Help.c add --guide option
Update commit message to explain the -g|--guide logic.

Patch 5 (now 4/5): Help.c: add list_common_guides_help() function
Removed the 'build artefact' /* */ comment line.
Note that these are just the common guides and used in a usage message.
The data was generated by a script variant of generate-cmdlist.sh

Patch (new 5/5): Help doc: Include --guide option description
Update the documentation/git-help.txt - I had been caught out by
the same 'focus on the code' mistake made by many and forgot
the documenation ;-)

Patch 6 - 13: 
All dropped.
Drop the separate guide list.txt and extraction script, which was
copied from the common command list and script. If the guide usage
list is useful, extend the command-list.txt and generate-cmdlist.sh
at a later date.

Drop the rename of user-manual and everyday because they are not
formatted as manuals. They can't be started by help's call to 'man'
(and possibly other paths) anyway.

Philip Oakley (5):
  Show 'git help <guide>' usage, with examples
  Help.c use OPT_COUNTUP
  Help.c add --guide option
  Help.c: add list_common_guides_help() function
  Help doc: Include --guide option description

 Documentation/git-help.txt | 28 +++++++++++++++++++++-------
 builtin/help.c             | 11 ++++++++---
 common-guides.h            | 11 +++++++++++
 git.c                      |  4 +++-
 help.c                     | 18 ++++++++++++++++++
 help.h                     |  1 +
 6 files changed, 62 insertions(+), 11 deletions(-)
 create mode 100644 common-guides.h

-- 
1.8.1.msysgit.1

[PATCH v2 4/5] Help.c: add list_common_guides_help() function

[Philip Oakley]

Re-use list_common_cmds_help but simply change the array name.
Candidate for future refactoring to pass a pointer to the array.

The common-guides.h list was generated with a simple variant of the
generate-cmdlist.sh and command-list.txt.

Do not list User-manual and Everday Git which not follow the naming
convention, nor gitrepository-layout which doesn't fit within the
name field size.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 builtin/help.c  |  1 +
 common-guides.h | 11 +++++++++++
 help.c          | 18 ++++++++++++++++++
 help.h          |  1 +
 4 files changed, 31 insertions(+)
 create mode 100644 common-guides.h

diff --git a/builtin/help.c b/builtin/help.c
index 6089d72..e21ffa5 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -434,6 +434,7 @@ int cmd_help(int argc, const char **argv, const char *prefix)
 		if (!show_guides) return 0;
 	}
 	if (show_guides) {
+		list_common_guides_help();
 		return 0;
 	}
 	if (!argv[0]) {
diff --git a/common-guides.h b/common-guides.h
new file mode 100644
index 0000000..0e94fdc
--- /dev/null
+++ b/common-guides.h
@@ -0,0 +1,11 @@
+/* re-use struct cmdname_help in common-commands.h */
+
+static struct cmdname_help common_guides[] = {
+  {"attributes", "defining attributes per path"},
+  {"glossary", "A GIT Glossary"},
+  {"ignore", "Specifies intentionally untracked files to ignore"},
+  {"modules", "defining submodule properties"},
+  {"revisions", "specifying revisions and ranges for git"},
+  {"tutorial", "A tutorial introduction to git (for version 1.5.1 or newer)"},
+  {"workflows", "An overview of recommended workflows with git"},
+};
diff --git a/help.c b/help.c
index 1dfa0b0..f4de407 100644
--- a/help.c
+++ b/help.c
@@ -4,6 +4,7 @@
 #include "levenshtein.h"
 #include "help.h"
 #include "common-cmds.h"
+#include "common-guides.h"
 #include "string-list.h"
 #include "column.h"
 #include "version.h"
@@ -240,6 +241,23 @@ void list_common_cmds_help(void)
 	}
 }
 
+void list_common_guides_help(void)
+{
+	int i, longest = 0;
+
+	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
+		if (longest < strlen(common_guides[i].name))
+			longest = strlen(common_guides[i].name);
+	}
+
+	puts(_("The common Git guides are:"));
+	for (i = 0; i < ARRAY_SIZE(common_guides); i++) {
+		printf("   %s   ", common_guides[i].name);
+		mput_char(' ', longest - strlen(common_guides[i].name));
+		puts(_(common_guides[i].help));
+	}
+}
+
 int is_in_cmdlist(struct cmdnames *c, const char *s)
 {
 	int i;
diff --git a/help.h b/help.h
index 0ae5a12..4ae1fd7 100644
--- a/help.h
+++ b/help.h
@@ -17,6 +17,7 @@ static inline void mput_char(char c, unsigned int num)
 }
 
 extern void list_common_cmds_help(void);
+extern void list_common_guides_help(void);
 extern const char *help_unknown_cmd(const char *cmd);
 extern void load_command_list(const char *prefix,
 			      struct cmdnames *main_cmds,
-- 
1.8.1.msysgit.1