Le 28 oct. 2025 à 18:27, Ruoyu Zhong via GitGitGadget [off-list ref] a écrit :

From: Ruoyu Zhong [off-list ref]

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/ (local)

Suggested-by: Ben Knoble <redacted>
Signed-off-by: Ruoyu Zhong <redacted>
---
   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