[PATCH v2] doc/git-bisect: clarify `git bisect run` syntax
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(-)
Show changes to 2 files +4 −4
Documentation/git-bisect.txt, builtin/bisect.c
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
