From 15f7d4943807a50e01d2fd85bcdbd44361808dd2 Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Tue, 2 Apr 2013 23:39:49 +0100 Subject: [PATCH 1/5] builtin/help.c: split "-a" processing into two "help -a" (help all) gives the list of available commands and then further gives hints on the use of "git help". Separate these into two steps, because we will add "help -g" (help guides) that want to also show the overall hints after it is done. While at it, change the definition of the "-a" option to use OPT_BOOL, not the deprecated OPT_BOOLEAN. We do not behave differently when the user gives the "-a" option multiple times, e.g. "git help -a -a". Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- builtin/help.c | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/builtin/help.c b/builtin/help.c index d1d71816a9d..8969d3b2b01 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_BOOL('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), @@ -428,7 +428,13 @@ int cmd_help(int argc, const char **argv, const char *prefix) git_config(git_help_config, NULL); printf(_("usage: %s%s"), _(git_usage_string), "\n\n"); list_commands(colopts, &main_cmds, &other_cmds); + } + + if (show_all) { printf("%s\n", _(git_more_info_string)); + /* + * We're done. Ignore any remaining args + */ return 0; } From 65f98358c0ca5917604d3eb59b80ce14f72c2c7c Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Tue, 2 Apr 2013 23:39:50 +0100 Subject: [PATCH 2/5] builtin/help.c: add --guide option Logic, but no actions, included. The --all commands option, if given, will display the list of available commands. The --guide option's list of guides 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 Signed-off-by: Junio C Hamano --- builtin/help.c | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/builtin/help.c b/builtin/help.c index 8969d3b2b01..03d432b19e9 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_BOOL('a', "all", &show_all, N_("print all available commands")), + OPT_BOOL('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 }; @@ -430,7 +432,11 @@ int cmd_help(int argc, const char **argv, const char *prefix) list_commands(colopts, &main_cmds, &other_cmds); } - if (show_all) { + if (show_guides) { + /* do action - next patch */ + } + + if (show_all || show_guides) { printf("%s\n", _(git_more_info_string)); /* * We're done. Ignore any remaining args From 002b726a400a1dea16c0b59ae61527a1e55799fb Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Tue, 2 Apr 2013 23:39:51 +0100 Subject: [PATCH 3/5] builtin/help.c: add list_common_guides_help() function This implements what "help -g" introduced in the previous step does. Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- builtin/help.c | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/builtin/help.c b/builtin/help.c index 03d432b19e9..034c36c254c 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -415,6 +415,37 @@ static void show_html_page(const char *git_cmd) open_html(page_path.buf); } +static struct { + const char *name; + const char *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"}, +}; + +static 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:\n")); + 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)); + } + putchar('\n'); +} + int cmd_help(int argc, const char **argv, const char *prefix) { int nongit; @@ -432,9 +463,8 @@ int cmd_help(int argc, const char **argv, const char *prefix) list_commands(colopts, &main_cmds, &other_cmds); } - if (show_guides) { - /* do action - next patch */ - } + if (show_guides) + list_common_guides_help(); if (show_all || show_guides) { printf("%s\n", _(git_more_info_string)); From 73903d0bcb00518e508f412a1d5c482b5094587e Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Tue, 2 Apr 2013 23:39:48 +0100 Subject: [PATCH 4/5] help: mention -a and -g option, and 'git help ' usage. Reword the overall help given at the end of "git help -a/-g" to mention how to get help on individual commands and concepts. Signed-off-by: Philip Oakley Signed-off-by: Junio C Hamano --- git.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/git.c b/git.c index 850d3f5527f..1ada169d5cf 100644 --- a/git.c +++ b/git.c @@ -13,7 +13,9 @@ const char git_usage_string[] = " []"; const char git_more_info_string[] = - N_("See 'git help ' for more information on a specific command."); + N_("'git help -a' and 'git help -g' lists available subcommands and some\n" + "concept guides. See 'git help ' or 'git help '\n" + "to read about a specific subcommand or concept."); static struct startup_info git_startup_info; static int use_pager = -1; From a133737b809a6556f087e590e862e8f29561710a Mon Sep 17 00:00:00 2001 From: Philip Oakley Date: Tue, 2 Apr 2013 23:39:52 +0100 Subject: [PATCH 5/5] doc: include --guide option description for "git help" 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 Signed-off-by: Junio C Hamano --- 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 e07b6dc19ad..b21e9d79be2 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 or 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 +If the option '--all' or '-a' is given, 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, a list of the useful +Git guides is also printed on the standard output. + +If a command, or a guide, is given, a manual page for that command or +guide 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 overrides any given command or guide name. + +-g:: +--guides:: + Prints a list of useful guides on the standard output. This + option overrides any given command or guide name. -i:: --info::