* [PATCH] bisect: update usage and docs to match each other
@ 2025-10-28 22:27 Ruoyu Zhong via GitGitGadget
2025-10-29 16:14 ` Ben Knoble
0 siblings, 1 reply; 2+ messages in thread
From: Ruoyu Zhong via GitGitGadget @ 2025-10-28 22:27 UTC (permalink / raw)
To: git; +Cc: Ben Knoble, Ruoyu Zhong, Ruoyu Zhong
From: Ruoyu Zhong <zhongruoyu@outlook.com>
Update the usage string of `git bisect` and documentation to match each
other. While at it, also:
1. Move the synopsis of `git bisect` subcommands to the synopsis
section, so that the test `t0450-txt-doc-vs-help.sh` can pass.
2. Document the `git bisect next` subcommand, which exists in the code
but is missing from the documentation.
See also: [1].
[1]: https://lore.kernel.org/git/3DA38465-7636-4EEF-B074-53E4628F5355@gmail.com/
Suggested-by: Ben Knoble <ben.knoble@gmail.com>
Signed-off-by: Ruoyu Zhong <zhongruoyu@outlook.com>
---
bisect: update usage and docs to match each other
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2084%2FZhongRuoyu%2Fgit-bisect-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2084/ZhongRuoyu/git-bisect-docs-v1
Pull-Request: https://github.com/git/git/pull/2084
Documentation/git-bisect.adoc | 43 +++++++++++++++++++++--------------
builtin/bisect.c | 21 ++++++++++-------
t/t0450/adoc-help-mismatches | 1 -
3 files changed, 39 insertions(+), 26 deletions(-)
diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc
index 58dbb74a15..b0078dda0e 100644
--- a/Documentation/git-bisect.adoc
+++ b/Documentation/git-bisect.adoc
@@ -9,26 +9,22 @@ git-bisect - Use binary search to find the commit that introduced a bug
SYNOPSIS
--------
[verse]
-'git bisect' <subcommand> <options>
+'git bisect' start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
+ [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
+'git bisect' (bad|new|<term-new>) [<rev>]
+'git bisect' (good|old|<term-old>) [<rev>...]
+'git bisect' terms [--term-(good|old) | --term-(bad|new)]
+'git bisect' skip [(<rev>|<range>)...]
+'git bisect' next
+'git bisect' reset [<commit>]
+'git bisect' (visualize|view)
+'git bisect' replay <logfile>
+'git bisect' log
+'git bisect' run <cmd> [<arg>...]
+'git bisect' help
DESCRIPTION
-----------
-The command takes various subcommands, and different options depending
-on the subcommand:
-
- git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
- [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
- git bisect (bad|new|<term-new>) [<rev>]
- git bisect (good|old|<term-old>) [<rev>...]
- git bisect terms [--term-(good|old) | --term-(bad|new)]
- git bisect skip [(<rev>|<range>)...]
- git bisect reset [<commit>]
- git bisect (visualize|view)
- git bisect replay <logfile>
- git bisect log
- git bisect run <cmd> [<arg>...]
- git bisect help
-
This command uses a binary search algorithm to find which commit in
your project's history introduced a bug. You use it by first telling
it a "bad" commit that is known to contain the bug, and a "good"
@@ -295,6 +291,19 @@ $ git bisect skip v2.5 v2.5..v2.6
This tells the bisect process that the commits between `v2.5` and
`v2.6` (inclusive) should be skipped.
+Bisect next
+~~~~~~~~~~~
+
+Normally, after marking a revision as good or bad, Git automatically
+computes and checks out the next revision to test. However, if you need to
+explicitly request the next bisection step, you can use:
+
+------------
+$ git bisect next
+------------
+
+You might use this to resume the bisection process after interrupting it
+by checking out a different revision.
Cutting down bisection by giving more parameters to bisect start
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/builtin/bisect.c b/builtin/bisect.c
index 8b8d870cd1..a500993bcb 100644
--- a/builtin/bisect.c
+++ b/builtin/bisect.c
@@ -27,13 +27,14 @@ 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>]" \
- " [--no-checkout] [--first-parent] [<bad> [<good>...]] [--]" \
- " [<pathspec>...]")
-#define BUILTIN_GIT_BISECT_STATE_USAGE \
- N_("git bisect (good|bad) [<rev>...]")
+ N_("git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]\n" \
+ " [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]")
+#define BUILTIN_GIT_BISECT_BAD_USAGE \
+ N_("git bisect (bad|new|<term-new>) [<rev>]")
+#define BUILTIN_GIT_BISECT_GOOD_USAGE \
+ N_("git bisect (good|old|<term-old>) [<rev>...]")
#define BUILTIN_GIT_BISECT_TERMS_USAGE \
- "git bisect terms [--term-good | --term-bad]"
+ "git bisect terms [--term-(good|old) | --term-(bad|new)]"
#define BUILTIN_GIT_BISECT_SKIP_USAGE \
N_("git bisect skip [(<rev>|<range>)...]")
#define BUILTIN_GIT_BISECT_NEXT_USAGE \
@@ -41,17 +42,20 @@ static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
#define BUILTIN_GIT_BISECT_RESET_USAGE \
N_("git bisect reset [<commit>]")
#define BUILTIN_GIT_BISECT_VISUALIZE_USAGE \
- "git bisect visualize"
+ "git bisect (visualize|view)"
#define BUILTIN_GIT_BISECT_REPLAY_USAGE \
N_("git bisect replay <logfile>")
#define BUILTIN_GIT_BISECT_LOG_USAGE \
"git bisect log"
#define BUILTIN_GIT_BISECT_RUN_USAGE \
N_("git bisect run <cmd> [<arg>...]")
+#define BUILTIN_GIT_BISECT_HELP_USAGE \
+ "git bisect help"
static const char * const git_bisect_usage[] = {
BUILTIN_GIT_BISECT_START_USAGE,
- BUILTIN_GIT_BISECT_STATE_USAGE,
+ BUILTIN_GIT_BISECT_BAD_USAGE,
+ BUILTIN_GIT_BISECT_GOOD_USAGE,
BUILTIN_GIT_BISECT_TERMS_USAGE,
BUILTIN_GIT_BISECT_SKIP_USAGE,
BUILTIN_GIT_BISECT_NEXT_USAGE,
@@ -60,6 +64,7 @@ static const char * const git_bisect_usage[] = {
BUILTIN_GIT_BISECT_REPLAY_USAGE,
BUILTIN_GIT_BISECT_LOG_USAGE,
BUILTIN_GIT_BISECT_RUN_USAGE,
+ BUILTIN_GIT_BISECT_HELP_USAGE,
NULL
};
diff --git a/t/t0450/adoc-help-mismatches b/t/t0450/adoc-help-mismatches
index 2c6ecd5fc8..8ee2d3f7c8 100644
--- a/t/t0450/adoc-help-mismatches
+++ b/t/t0450/adoc-help-mismatches
@@ -2,7 +2,6 @@ add
am
apply
archive
-bisect
blame
branch
check-ref-format
base-commit: 57da342c786f59eaeb436c18635cc1c7597733d9
--
gitgitgadget
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH] bisect: update usage and docs to match each other
2025-10-28 22:27 [PATCH] bisect: update usage and docs to match each other Ruoyu Zhong via GitGitGadget
@ 2025-10-29 16:14 ` Ben Knoble
0 siblings, 0 replies; 2+ messages in thread
From: Ben Knoble @ 2025-10-29 16:14 UTC (permalink / raw)
To: Ruoyu Zhong via GitGitGadget; +Cc: git, Ruoyu Zhong
> Le 28 oct. 2025 à 18:27, Ruoyu Zhong via GitGitGadget <gitgitgadget@gmail.com> a écrit :
>
> From: Ruoyu Zhong <zhongruoyu@outlook.com>
>
> Update the usage string of `git bisect` and documentation to match each
> other. While at it, also:
>
> 1. Move the synopsis of `git bisect` subcommands to the synopsis
> section, so that the test `t0450-txt-doc-vs-help.sh` can pass.
>
> 2. Document the `git bisect next` subcommand, which exists in the code
> but is missing from the documentation.
>
> See also: [1].
>
> [1]: https://lore.kernel.org/git/3DA38465-7636-4EEF-B074-53E4628F5355@gmail.com/
>
> Suggested-by: Ben Knoble <ben.knoble@gmail.com>
> Signed-off-by: Ruoyu Zhong <zhongruoyu@outlook.com>
> ---
> bisect: update usage and docs to match each other
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2084%2FZhongRuoyu%2Fgit-bisect-docs-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2084/ZhongRuoyu/git-bisect-docs-v1
> Pull-Request: https://github.com/git/git/pull/2084
>
> Documentation/git-bisect.adoc | 43 +++++++++++++++++++++--------------
> builtin/bisect.c | 21 ++++++++++-------
> t/t0450/adoc-help-mismatches | 1 -
> 3 files changed, 39 insertions(+), 26 deletions(-)
>
> diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc
> index 58dbb74a15..b0078dda0e 100644
> --- a/Documentation/git-bisect.adoc
> +++ b/Documentation/git-bisect.adoc
> @@ -9,26 +9,22 @@ git-bisect - Use binary search to find the commit that introduced a bug
> SYNOPSIS
> --------
> [verse]
> -'git bisect' <subcommand> <options>
> +'git bisect' start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
> + [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
> +'git bisect' (bad|new|<term-new>) [<rev>]
> +'git bisect' (good|old|<term-old>) [<rev>...]
> +'git bisect' terms [--term-(good|old) | --term-(bad|new)]
> +'git bisect' skip [(<rev>|<range>)...]
> +'git bisect' next
> +'git bisect' reset [<commit>]
> +'git bisect' (visualize|view)
> +'git bisect' replay <logfile>
> +'git bisect' log
> +'git bisect' run <cmd> [<arg>...]
> +'git bisect' help
>
> DESCRIPTION
> -----------
> -The command takes various subcommands, and different options depending
> -on the subcommand:
> -
> - git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
> - [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
> - git bisect (bad|new|<term-new>) [<rev>]
> - git bisect (good|old|<term-old>) [<rev>...]
> - git bisect terms [--term-(good|old) | --term-(bad|new)]
> - git bisect skip [(<rev>|<range>)...]
> - git bisect reset [<commit>]
> - git bisect (visualize|view)
> - git bisect replay <logfile>
> - git bisect log
> - git bisect run <cmd> [<arg>...]
> - git bisect help
> -
> This command uses a binary search algorithm to find which commit in
> your project's history introduced a bug. You use it by first telling
> it a "bad" commit that is known to contain the bug, and a "good"
> @@ -295,6 +291,19 @@ $ git bisect skip v2.5 v2.5..v2.6
> This tells the bisect process that the commits between `v2.5` and
> `v2.6` (inclusive) should be skipped.
>
> +Bisect next
> +~~~~~~~~~~~
> +
> +Normally, after marking a revision as good or bad, Git automatically
> +computes and checks out the next revision to test. However, if you need to
> +explicitly request the next bisection step, you can use:
> +
> +------------
> +$ git bisect next
> +------------
> +
> +You might use this to resume the bisection process after interrupting it
> +by checking out a different revision.
>
> Cutting down bisection by giving more parameters to bisect start
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> diff --git a/builtin/bisect.c b/builtin/bisect.c
> index 8b8d870cd1..a500993bcb 100644
> --- a/builtin/bisect.c
> +++ b/builtin/bisect.c
> @@ -27,13 +27,14 @@ 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>]" \
> - " [--no-checkout] [--first-parent] [<bad> [<good>...]] [--]" \
> - " [<pathspec>...]")
> -#define BUILTIN_GIT_BISECT_STATE_USAGE \
> - N_("git bisect (good|bad) [<rev>...]")
> + N_("git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]\n" \
> + " [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]")
> +#define BUILTIN_GIT_BISECT_BAD_USAGE \
> + N_("git bisect (bad|new|<term-new>) [<rev>]")
> +#define BUILTIN_GIT_BISECT_GOOD_USAGE \
> + N_("git bisect (good|old|<term-old>) [<rev>...]")
> #define BUILTIN_GIT_BISECT_TERMS_USAGE \
> - "git bisect terms [--term-good | --term-bad]"
> + "git bisect terms [--term-(good|old) | --term-(bad|new)]"
> #define BUILTIN_GIT_BISECT_SKIP_USAGE \
> N_("git bisect skip [(<rev>|<range>)...]")
> #define BUILTIN_GIT_BISECT_NEXT_USAGE \
> @@ -41,17 +42,20 @@ static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
> #define BUILTIN_GIT_BISECT_RESET_USAGE \
> N_("git bisect reset [<commit>]")
> #define BUILTIN_GIT_BISECT_VISUALIZE_USAGE \
> - "git bisect visualize"
> + "git bisect (visualize|view)"
> #define BUILTIN_GIT_BISECT_REPLAY_USAGE \
> N_("git bisect replay <logfile>")
> #define BUILTIN_GIT_BISECT_LOG_USAGE \
> "git bisect log"
> #define BUILTIN_GIT_BISECT_RUN_USAGE \
> N_("git bisect run <cmd> [<arg>...]")
> +#define BUILTIN_GIT_BISECT_HELP_USAGE \
> + "git bisect help"
>
> static const char * const git_bisect_usage[] = {
> BUILTIN_GIT_BISECT_START_USAGE,
> - BUILTIN_GIT_BISECT_STATE_USAGE,
> + BUILTIN_GIT_BISECT_BAD_USAGE,
> + BUILTIN_GIT_BISECT_GOOD_USAGE,
> BUILTIN_GIT_BISECT_TERMS_USAGE,
> BUILTIN_GIT_BISECT_SKIP_USAGE,
> BUILTIN_GIT_BISECT_NEXT_USAGE,
> @@ -60,6 +64,7 @@ static const char * const git_bisect_usage[] = {
> BUILTIN_GIT_BISECT_REPLAY_USAGE,
> BUILTIN_GIT_BISECT_LOG_USAGE,
> BUILTIN_GIT_BISECT_RUN_USAGE,
> + BUILTIN_GIT_BISECT_HELP_USAGE,
> NULL
> };
>
> diff --git a/t/t0450/adoc-help-mismatches b/t/t0450/adoc-help-mismatches
> index 2c6ecd5fc8..8ee2d3f7c8 100644
> --- a/t/t0450/adoc-help-mismatches
> +++ b/t/t0450/adoc-help-mismatches
> @@ -2,7 +2,6 @@ add
> am
> apply
> archive
> -bisect
> blame
> branch
> check-ref-format
>
> base-commit: 57da342c786f59eaeb436c18635cc1c7597733d9
> --
> gitgitgadget
Nothing particularly surprising here, I think. Thanks!
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2025-10-29 16:14 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-10-28 22:27 [PATCH] bisect: update usage and docs to match each other Ruoyu Zhong via GitGitGadget
2025-10-29 16:14 ` Ben Knoble
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).