From d7f817d376134ec09e6804cdb6e3d062e3308eb9 Mon Sep 17 00:00:00 2001 From: Ævar Arnfjörð Bjarmason Date: Mon, 21 Feb 2022 20:38:48 +0100 Subject: help: note the option name on option incompatibility MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change the errors added in d35d03cf93e (help: simplify by moving to OPT_CMDMODE(), 2021-09-22) to quote the offending option at the user when invoked as e.g.: git help --guides garbage Now instead of: fatal: this option doesn't take any other arguments We'll emit: fatal: the '--guides' option doesn't take any non-option arguments Let's also rename the function, as it will be extended to do other checks that aren't "no extra argc" in a subsequent commit. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- builtin/help.c | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'builtin/help.c') diff --git a/builtin/help.c b/builtin/help.c index d387131dd8..1c1581ef85 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -574,11 +574,12 @@ static const char *check_git_cmd(const char* cmd) return cmd; } -static void no_extra_argc(int argc) +static void opt_mode_usage(int argc, const char *opt_mode) { if (argc) - usage_msg_opt(_("this option doesn't take any other arguments"), - builtin_help_usage, builtin_help_options); + usage_msg_optf(_("the '%s' option doesn't take any non-option arguments"), + builtin_help_usage, builtin_help_options, + opt_mode); } int cmd_help(int argc, const char **argv, const char *prefix) @@ -604,20 +605,20 @@ int cmd_help(int argc, const char **argv, const char *prefix) printf("%s\n", _(git_more_info_string)); break; case HELP_ACTION_GUIDES: - no_extra_argc(argc); + opt_mode_usage(argc, "--guides"); list_guides_help(); printf("%s\n", _(git_more_info_string)); return 0; case HELP_ACTION_CONFIG_FOR_COMPLETION: - no_extra_argc(argc); + opt_mode_usage(argc, "--config-for-completion"); list_config_help(SHOW_CONFIG_VARS); return 0; case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION: - no_extra_argc(argc); + opt_mode_usage(argc, "--config-sections-for-completion"); list_config_help(SHOW_CONFIG_SECTIONS); return 0; case HELP_ACTION_CONFIG: - no_extra_argc(argc); + opt_mode_usage(argc, "--config"); setup_pager(); list_config_help(SHOW_CONFIG_HUMAN); printf("\n%s\n", _("'git help config' for more information")); -- cgit v1.2.3 From 5e8068b74df8d0c58042a3ffe1c09dbffbbc63f7 Mon Sep 17 00:00:00 2001 From: Ævar Arnfjörð Bjarmason Date: Mon, 21 Feb 2022 20:38:49 +0100 Subject: help: correct usage & behavior of "git help --all" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Do the same for the "--all" option that I did for "--guides" in 9856ea6785c (help: correct usage & behavior of "git help --guides", 2021-09-22). I.e. we've documented it as ignoring non-option arguments, let's have it error out instead. As with other changes made in 62f035aee3f (Merge branch 'ab/help-config-vars', 2021-10-13) this is technically a change in behavior, but in practice it's just a bug fix. We were ignoring this before, but by erroring we can simplify our documentation and synopsis, as well as avoid user confusion as they wonder what the difference between e.g. "git help --all" and "git help --all status" is (there wasn't any difference). Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/git-help.txt | 5 ++--- builtin/help.c | 5 +++-- t/t0012-help.sh | 3 +++ 3 files changed, 8 insertions(+), 5 deletions(-) (limited to 'builtin/help.c') diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index cf1d53e949..d07590c8ff 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git help' [-a|--all] [--[no-]verbose] - [[-i|--info] [-m|--man] [-w|--web]] [|] +'git help' [[-i|--info] [-m|--man] [-w|--web]] [|] 'git help' [-g|--guides] 'git help' [-c|--config] @@ -46,8 +46,7 @@ OPTIONS ------- -a:: --all:: - Prints all the available commands on the standard output. This - option overrides any given command or guide name. + Prints all the available commands on the standard output. --verbose:: When used with `--all` print description for all recognized diff --git a/builtin/help.c b/builtin/help.c index 1c1581ef85..b682446bbf 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -75,8 +75,8 @@ static struct option builtin_help_options[] = { }; static const char * const builtin_help_usage[] = { - N_("git help [-a|--all] [--[no-]verbose]]\n" - " [[-i|--info] [-m|--man] [-w|--web]] []"), + N_("git help [-a|--all] [--[no-]verbose]]"), + N_("git help [[-i|--info] [-m|--man] [-w|--web]] []"), N_("git help [-g|--guides]"), N_("git help [-c|--config]"), NULL @@ -594,6 +594,7 @@ int cmd_help(int argc, const char **argv, const char *prefix) switch (cmd_mode) { case HELP_ACTION_ALL: + opt_mode_usage(argc, "--all"); if (verbose) { setup_pager(); list_all_cmds_help(); diff --git a/t/t0012-help.sh b/t/t0012-help.sh index 9ac3f5d3c4..c87730aa92 100755 --- a/t/t0012-help.sh +++ b/t/t0012-help.sh @@ -35,6 +35,9 @@ test_expect_success 'basic help commands' ' ' test_expect_success 'invalid usage' ' + test_expect_code 129 git help -a add && + test_expect_code 129 git help --all add && + test_expect_code 129 git help -g add && test_expect_code 129 git help -a -c && -- cgit v1.2.3 From 503cddacb63b9a37d063de5b11ac188de822e06f Mon Sep 17 00:00:00 2001 From: Ævar Arnfjörð Bjarmason Date: Mon, 21 Feb 2022 20:38:50 +0100 Subject: help: error if [-a|-g|-c] and [-i|-m|-w] are combined MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add more sanity checking to "git help" usage by erroring out if these man viewer options are combined with incompatible command-modes that will never use these documentation viewers. This continues the work started in d35d03cf93e (help: simplify by moving to OPT_CMDMODE(), 2021-09-22) of adding more sanity checking to "git help". Doing this allows us to clarify the "SYNOPSIS" in the documentation, and the "git help -h" output. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- builtin/help.c | 41 +++++++++++++++++++++++++++++++++++------ t/t0012-help.sh | 10 ++++++++++ 2 files changed, 45 insertions(+), 6 deletions(-) (limited to 'builtin/help.c') diff --git a/builtin/help.c b/builtin/help.c index b682446bbf..1fc45adfcc 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -574,12 +574,40 @@ static const char *check_git_cmd(const char* cmd) return cmd; } -static void opt_mode_usage(int argc, const char *opt_mode) +static void no_help_format(const char *opt_mode, enum help_format fmt) +{ + const char *opt_fmt; + + switch (fmt) { + case HELP_FORMAT_NONE: + return; + case HELP_FORMAT_MAN: + opt_fmt = "--man"; + break; + case HELP_FORMAT_INFO: + opt_fmt = "--info"; + break; + case HELP_FORMAT_WEB: + opt_fmt = "--web"; + break; + default: + BUG("unreachable"); + } + + usage_msg_optf(_("options '%s' and '%s' cannot be used together"), + builtin_help_usage, builtin_help_options, opt_mode, + opt_fmt); +} + +static void opt_mode_usage(int argc, const char *opt_mode, + enum help_format fmt) { if (argc) usage_msg_optf(_("the '%s' option doesn't take any non-option arguments"), builtin_help_usage, builtin_help_options, opt_mode); + + no_help_format(opt_mode, fmt); } int cmd_help(int argc, const char **argv, const char *prefix) @@ -594,7 +622,7 @@ int cmd_help(int argc, const char **argv, const char *prefix) switch (cmd_mode) { case HELP_ACTION_ALL: - opt_mode_usage(argc, "--all"); + opt_mode_usage(argc, "--all", help_format); if (verbose) { setup_pager(); list_all_cmds_help(); @@ -606,20 +634,21 @@ int cmd_help(int argc, const char **argv, const char *prefix) printf("%s\n", _(git_more_info_string)); break; case HELP_ACTION_GUIDES: - opt_mode_usage(argc, "--guides"); + opt_mode_usage(argc, "--guides", help_format); list_guides_help(); printf("%s\n", _(git_more_info_string)); return 0; case HELP_ACTION_CONFIG_FOR_COMPLETION: - opt_mode_usage(argc, "--config-for-completion"); + opt_mode_usage(argc, "--config-for-completion", help_format); list_config_help(SHOW_CONFIG_VARS); return 0; case HELP_ACTION_CONFIG_SECTIONS_FOR_COMPLETION: - opt_mode_usage(argc, "--config-sections-for-completion"); + opt_mode_usage(argc, "--config-sections-for-completion", + help_format); list_config_help(SHOW_CONFIG_SECTIONS); return 0; case HELP_ACTION_CONFIG: - opt_mode_usage(argc, "--config"); + opt_mode_usage(argc, "--config", help_format); setup_pager(); list_config_help(SHOW_CONFIG_HUMAN); printf("\n%s\n", _("'git help config' for more information")); diff --git a/t/t0012-help.sh b/t/t0012-help.sh index c87730aa92..f12783fd15 100755 --- a/t/t0012-help.sh +++ b/t/t0012-help.sh @@ -49,6 +49,16 @@ test_expect_success 'invalid usage' ' test_expect_code 129 git help --config-sections-for-completion add ' +for opt in '-a' '-g' '-c' '--config-for-completion' '--config-sections-for-completion' +do + test_expect_success "invalid usage of '$opt' with [-i|-m|-w]" ' + git help $opt && + test_expect_code 129 git help $opt -i && + test_expect_code 129 git help $opt -m && + test_expect_code 129 git help $opt -w + ' +done + test_expect_success "works for commands and guides by default" ' configure_help && git help status && -- cgit v1.2.3 From 1ce590133b545aa735683f46003d12df624d67af Mon Sep 17 00:00:00 2001 From: Ævar Arnfjörð Bjarmason Date: Mon, 21 Feb 2022 20:38:51 +0100 Subject: help: add --no-[external-commands|aliases] for use with --all MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add the ability to only emit git's own usage information under --all. This also allows us to extend the "test_section_spacing" tests added in a preceding commit to test "git help --all" output. Previously we could not do that, as the tests might find a git-* command in the "$PATH", which would make the output differ from one setup to another. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/git-help.txt | 10 +++++++++- builtin/help.c | 16 ++++++++++++++-- help.c | 8 +++++--- help.h | 2 +- t/t0012-help.sh | 37 +++++++++++++++++++++++++++++++++++++ 5 files changed, 66 insertions(+), 7 deletions(-) (limited to 'builtin/help.c') diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index d07590c8ff..239c68db45 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -8,7 +8,7 @@ git-help - Display help information about Git SYNOPSIS -------- [verse] -'git help' [-a|--all] [--[no-]verbose] +'git help' [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases] 'git help' [[-i|--info] [-m|--man] [-w|--web]] [|] 'git help' [-g|--guides] 'git help' [-c|--config] @@ -48,6 +48,14 @@ OPTIONS --all:: Prints all the available commands on the standard output. +--no-external-commands:: + When used with `--all`, exclude the listing of external "git-*" + commands found in the `$PATH`. + +--no-aliases:: + When used with `--all`, exclude the listing of configured + aliases. + --verbose:: When used with `--all` print description for all recognized commands. This is the default. diff --git a/builtin/help.c b/builtin/help.c index 1fc45adfcc..01eda326c3 100644 --- a/builtin/help.c +++ b/builtin/help.c @@ -51,9 +51,14 @@ static const char *html_path; static int verbose = 1; static enum help_format help_format = HELP_FORMAT_NONE; static int exclude_guides; +static int show_external_commands = -1; +static int show_aliases = -1; static struct option builtin_help_options[] = { OPT_CMDMODE('a', "all", &cmd_mode, N_("print all available commands"), HELP_ACTION_ALL), + OPT_BOOL(0, "external-commands", &show_external_commands, + N_("show external commands in --all")), + OPT_BOOL(0, "aliases", &show_aliases, N_("show aliases in --all")), OPT_HIDDEN_BOOL(0, "exclude-guides", &exclude_guides, N_("exclude 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"), @@ -75,7 +80,7 @@ static struct option builtin_help_options[] = { }; static const char * const builtin_help_usage[] = { - N_("git help [-a|--all] [--[no-]verbose]]"), + N_("git help [-a|--all] [--[no-]verbose]] [--[no-]external-commands] [--[no-]aliases]"), N_("git help [[-i|--info] [-m|--man] [-w|--web]] []"), N_("git help [-g|--guides]"), N_("git help [-c|--config]"), @@ -620,12 +625,19 @@ int cmd_help(int argc, const char **argv, const char *prefix) builtin_help_usage, 0); parsed_help_format = help_format; + if (cmd_mode != HELP_ACTION_ALL && + (show_external_commands >= 0 || + show_aliases >= 0)) + usage_msg_opt(_("the '--no-[external-commands|aliases]' options can only be used with '--all'"), + builtin_help_usage, builtin_help_options); + switch (cmd_mode) { case HELP_ACTION_ALL: opt_mode_usage(argc, "--all", help_format); if (verbose) { setup_pager(); - list_all_cmds_help(); + list_all_cmds_help(show_external_commands, + show_aliases); return 0; } printf(_("usage: %s%s"), _(git_usage_string), "\n\n"); diff --git a/help.c b/help.c index 004117347e..45a21e7e35 100644 --- a/help.c +++ b/help.c @@ -476,15 +476,17 @@ static void list_all_cmds_help_aliases(int longest) string_list_clear(&alias_list, 1); } -void list_all_cmds_help(void) +void list_all_cmds_help(int show_external_commands, int show_aliases) { int longest; puts(_("See 'git help ' to read about a specific subcommand")); print_cmd_by_category(main_categories, &longest); - list_all_cmds_help_external_commands(); - list_all_cmds_help_aliases(longest); + if (show_external_commands) + list_all_cmds_help_external_commands(); + if (show_aliases) + list_all_cmds_help_aliases(longest); } int is_in_cmdlist(struct cmdnames *c, const char *s) diff --git a/help.h b/help.h index 9d383f1a0b..971a3ad855 100644 --- a/help.h +++ b/help.h @@ -20,7 +20,7 @@ static inline void mput_char(char c, unsigned int num) } void list_common_cmds_help(void); -void list_all_cmds_help(void); +void list_all_cmds_help(int show_external_commands, int show_aliases); void list_guides_help(void); void list_all_main_cmds(struct string_list *list); diff --git a/t/t0012-help.sh b/t/t0012-help.sh index f12783fd15..64321480c6 100755 --- a/t/t0012-help.sh +++ b/t/t0012-help.sh @@ -57,6 +57,19 @@ do test_expect_code 129 git help $opt -m && test_expect_code 129 git help $opt -w ' + + if test "$opt" = "-a" + then + continue + fi + + test_expect_success "invalid usage of '$opt' with --no-external-commands" ' + test_expect_code 129 git help $opt --no-external-commands + ' + + test_expect_success "invalid usage of '$opt' with --no-aliases" ' + test_expect_code 129 git help $opt --no-external-commands + ' done test_expect_success "works for commands and guides by default" ' @@ -187,6 +200,30 @@ do ' done +test_expect_success "'git help -a' section spacing" ' + test_section_spacing \ + git help -a --no-external-commands --no-aliases <<-\EOF && + See '\''git help '\'' to read about a specific subcommand + + Main Porcelain Commands + + Ancillary Commands / Manipulators + + Ancillary Commands / Interrogators + + Interacting with Others + + Low-level Commands / Manipulators + + Low-level Commands / Interrogators + + Low-level Commands / Syncing Repositories + + Low-level Commands / Internal Helpers + EOF + test_cmp expect actual +' + test_expect_success "'git help -g' section spacing" ' test_section_spacing_trailer git help -g <<-\EOF && -- cgit v1.2.3