Subject: Re: [PATCH v2 6/9] help: correct usage & behavior of "git help --all"

From: Junio C Hamano <[email-masked]>
Date: Wed, 23 Feb 2022 14:12:30 -0800

Ævar Arnfjörð Bjarmason  <[email-masked]> writes:

> diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
> index cf1d53e9499..d07590c8ff7 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]] [<command>|<guide>]
> +'git help' [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]

Hmph, OK.  The earlier one made it appear that when -a is given to
"git help" it would also accept command or guide, which is no longer
true.

>  'git help' [-g|--guides]
>  'git help' [-c|--config]

This is not new, but don't we need to fix the mark-up of [-a|--all]
and [-g|--guides] and [-c|--config]?  It's not like "We can give 0
or more of i/-m/-w".  These are "we have to give either -a or --all
to trigger this mode".

> diff --git a/builtin/help.c b/builtin/help.c
> index 1c1581ef850..b682446bbf5 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]] [<command>]"),
> +	N_("git help [-a|--all] [--[no-]verbose]]"),
> +	N_("git help [[-i|--info] [-m|--man] [-w|--web]] [<command>]"),
>  	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");

OK.

>  		if (verbose) {
>  			setup_pager();
>  			list_all_cmds_help();
> diff --git a/t/t0012-help.sh b/t/t0012-help.sh
> index 9ac3f5d3c4b..c87730aa920 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 &&