[PATCH v2] doc/git-bisect: clarify `git bisect run` syntax

["cousteau via GitGitGadget" <gitgitgadget@gmail.com>]

From: Javier Mora <cousteaulecommandant@gmail.com>

The description of the `git bisect run` command syntax at the beginning
of the manpage is `git bisect run <cmd>...`, which isn't quite clear
about what `<cmd>` is or what the `...` mean; one could think that it is
the whole (quoted) command line with all arguments in a single string,
or that it supports multiple commands, or that it doesn't accept
commands with arguments at all.

Change to `git bisect run <cmd> [<arg>...]` to clarify the syntax,
in both the manpage and the `git bisect -h` command output.

Additionally, change `--term-{new,bad}` et al to `--term-(new|bad)`
for consistency with the synopsis syntax conventions.

Signed-off-by: Javier Mora <cousteaulecommandant@gmail.com>
---
    doc/git-bisect: clarify git bisect run syntax
    
    I saw someone in IRC wondering about the syntax for git bisect run for a
    command with arguments, and found that its short description at the
    beginning of the manpage is not very clear (although it gets clarified
    later when it is properly described). It describes the syntax as git
    bisect run <cmd>... which is a bit confusing; it should say git bisect
    run <cmd> [<arg>...], otherwise it somehow looks like you have to "enter
    one or more commands", and that each command is a single argument.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1602%2Fcousteaulecommandant%2Fman-git-bisect-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1602/cousteaulecommandant/man-git-bisect-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1602

Range-diff vs v1:

 1:  ce4c60a6f4f ! 1:  8de70bb060e doc/git-bisect: clarify `git bisect run` syntax
     @@ Commit message
          or that it supports multiple commands, or that it doesn't accept
          commands with arguments at all.
      
     -    Change to `git bisect run <cmd> [<arg>...]` to clarify the syntax.
     +    Change to `git bisect run <cmd> [<arg>...]` to clarify the syntax,
     +    in both the manpage and the `git bisect -h` command output.
     +
     +    Additionally, change `--term-{new,bad}` et al to `--term-(new|bad)`
     +    for consistency with the synopsis syntax conventions.
      
          Signed-off-by: Javier Mora <cousteaulecommandant@gmail.com>
      
       ## Documentation/git-bisect.txt ##
     +@@ Documentation/git-bisect.txt: DESCRIPTION
     + The command takes various subcommands, and different options depending
     + on the subcommand:
     + 
     +- git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]
     ++ git bisect start [--term-(new|bad)=<term-new> --term-(old|good)=<term-old>]
     + 		  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...]
     +  git bisect (bad|new|<term-new>) [<rev>]
     +  git bisect (good|old|<term-old>) [<rev>...]
      @@ Documentation/git-bisect.txt: on the subcommand:
        git bisect (visualize|view)
        git bisect replay <logfile>
     @@ Documentation/git-bisect.txt: on the subcommand:
        git bisect help
       
       This command uses a binary search algorithm to find which commit in
     +
     + ## builtin/bisect.c ##
     +@@ builtin/bisect.c: static GIT_PATH_FUNC(git_path_bisect_first_parent, "BISECT_FIRST_PARENT")
     + static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
     + 
     + #define BUILTIN_GIT_BISECT_START_USAGE \
     +-	N_("git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]" \
     ++	N_("git bisect start [--term-(new|bad)=<term> --term-(old|good)=<term>]" \
     + 	   "    [--no-checkout] [--first-parent] [<bad> [<good>...]] [--]" \
     + 	   "    [<pathspec>...]")
     + #define BUILTIN_GIT_BISECT_STATE_USAGE \
     +@@ builtin/bisect.c: static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
     + #define BUILTIN_GIT_BISECT_LOG_USAGE \
     + 	"git bisect log"
     + #define BUILTIN_GIT_BISECT_RUN_USAGE \
     +-	N_("git bisect run <cmd>...")
     ++	N_("git bisect run <cmd> [<arg>...]")
     + 
     + static const char * const git_bisect_usage[] = {
     + 	BUILTIN_GIT_BISECT_START_USAGE,


 Documentation/git-bisect.txt | 4 ++--
 builtin/bisect.c             | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index 7872dba3aef..191b4a42b6d 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -16,7 +16,7 @@ DESCRIPTION
 The command takes various subcommands, and different options depending
 on the subcommand:
 
- git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]
+ git bisect start [--term-(new|bad)=<term-new> --term-(old|good)=<term-old>]
 		  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...]
  git bisect (bad|new|<term-new>) [<rev>]
  git bisect (good|old|<term-old>) [<rev>...]
@@ -26,7 +26,7 @@ on the subcommand:
  git bisect (visualize|view)
  git bisect replay <logfile>
  git bisect log
- git bisect run <cmd>...
+ git bisect run <cmd> [<arg>...]
  git bisect help
 
 This command uses a binary search algorithm to find which commit in
diff --git a/builtin/bisect.c b/builtin/bisect.c
index 65478ef40f5..35938b05fd1 100644
--- a/builtin/bisect.c
+++ b/builtin/bisect.c
@@ -26,7 +26,7 @@ static GIT_PATH_FUNC(git_path_bisect_first_parent, "BISECT_FIRST_PARENT")
 static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
 
 #define BUILTIN_GIT_BISECT_START_USAGE \
-	N_("git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]" \
+	N_("git bisect start [--term-(new|bad)=<term> --term-(old|good)=<term>]" \
 	   "    [--no-checkout] [--first-parent] [<bad> [<good>...]] [--]" \
 	   "    [<pathspec>...]")
 #define BUILTIN_GIT_BISECT_STATE_USAGE \
@@ -46,7 +46,7 @@ static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
 #define BUILTIN_GIT_BISECT_LOG_USAGE \
 	"git bisect log"
 #define BUILTIN_GIT_BISECT_RUN_USAGE \
-	N_("git bisect run <cmd>...")
+	N_("git bisect run <cmd> [<arg>...]")
 
 static const char * const git_bisect_usage[] = {
 	BUILTIN_GIT_BISECT_START_USAGE,

base-commit: ceadf0f3cf51550166a387ec8508bb55e7883057
-- 
gitgitgadget