bisect: update usage and docs to match each other
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ruoyu Zhong committed
Oct 28, 2025 at 22:27 UTC
bb42dc971074ebe83697943b364350e19e4c0911
3 files changed
+39
-26
Documentation/git-bisect.adoc
+26
-17
@@ -9,26 +9,22 @@ git-bisect - Use binary search to find the commit that introduced a bug
9
SYNOPSIS
10
--------
11
[verse]
12
-'git bisect' <subcommand> <options>
12
+'git bisect' start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
13
+ [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
14
+'git bisect' (bad|new|<term-new>) [<rev>]
15
+'git bisect' (good|old|<term-old>) [<rev>...]
16
+'git bisect' terms [--term-(good|old) | --term-(bad|new)]
17
+'git bisect' skip [(<rev>|<range>)...]
18
+'git bisect' next
19
+'git bisect' reset [<commit>]
20
+'git bisect' (visualize|view)
21
+'git bisect' replay <logfile>
22
+'git bisect' log
23
+'git bisect' run <cmd> [<arg>...]
24
+'git bisect' help
25
26
DESCRIPTION
27
-----------
16
-The command takes various subcommands, and different options depending
17
-on the subcommand:
18
-
19
- git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
20
- [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
21
- git bisect (bad|new|<term-new>) [<rev>]
22
- git bisect (good|old|<term-old>) [<rev>...]
23
- git bisect terms [--term-(good|old) | --term-(bad|new)]
24
- git bisect skip [(<rev>|<range>)...]
25
- git bisect reset [<commit>]
26
- git bisect (visualize|view)
27
- git bisect replay <logfile>
28
- git bisect log
29
- git bisect run <cmd> [<arg>...]
30
- git bisect help
31
-
28
This command uses a binary search algorithm to find which commit in
29
your project's history introduced a bug. You use it by first telling
30
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
291
This tells the bisect process that the commits between `v2.5` and
292
`v2.6` (inclusive) should be skipped.
293
294
+Bisect next
295
+~~~~~~~~~~~
296
+
297
+Normally, after marking a revision as good or bad, Git automatically
298
+computes and checks out the next revision to test. However, if you need to
299
+explicitly request the next bisection step, you can use:
300
+
301
+------------
302
+$ git bisect next
303
+------------
304
+
305
+You might use this to resume the bisection process after interrupting it
306
+by checking out a different revision.
307
308
Cutting down bisection by giving more parameters to bisect start
309
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
builtin/bisect.c
+13
-8
@@ -27,13 +27,14 @@ static GIT_PATH_FUNC(git_path_bisect_first_parent, "BISECT_FIRST_PARENT")
27
static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
28
29
#define BUILTIN_GIT_BISECT_START_USAGE \
30
- N_("git bisect start [--term-(new|bad)=<term> --term-(old|good)=<term>]" \
31
- " [--no-checkout] [--first-parent] [<bad> [<good>...]] [--]" \
32
- " [<pathspec>...]")
33
-#define BUILTIN_GIT_BISECT_STATE_USAGE \
34
- N_("git bisect (good|bad) [<rev>...]")
30
+ N_("git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]\n" \
31
+ " [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]")
32
+#define BUILTIN_GIT_BISECT_BAD_USAGE \
33
+ N_("git bisect (bad|new|<term-new>) [<rev>]")
34
+#define BUILTIN_GIT_BISECT_GOOD_USAGE \
35
+ N_("git bisect (good|old|<term-old>) [<rev>...]")
36
#define BUILTIN_GIT_BISECT_TERMS_USAGE \
36
- "git bisect terms [--term-good | --term-bad]"
37
+ "git bisect terms [--term-(good|old) | --term-(bad|new)]"
38
#define BUILTIN_GIT_BISECT_SKIP_USAGE \
39
N_("git bisect skip [(<rev>|<range>)...]")
40
#define BUILTIN_GIT_BISECT_NEXT_USAGE \
@@ -41,17 +42,20 @@ static GIT_PATH_FUNC(git_path_bisect_run, "BISECT_RUN")
42
#define BUILTIN_GIT_BISECT_RESET_USAGE \
43
N_("git bisect reset [<commit>]")
44
#define BUILTIN_GIT_BISECT_VISUALIZE_USAGE \
44
- "git bisect visualize"
45
+ "git bisect (visualize|view)"
46
#define BUILTIN_GIT_BISECT_REPLAY_USAGE \
47
N_("git bisect replay <logfile>")
48
#define BUILTIN_GIT_BISECT_LOG_USAGE \
49
"git bisect log"
50
#define BUILTIN_GIT_BISECT_RUN_USAGE \
51
N_("git bisect run <cmd> [<arg>...]")
52
+#define BUILTIN_GIT_BISECT_HELP_USAGE \
53
+ "git bisect help"
54
55
static const char * const git_bisect_usage[] = {
56
BUILTIN_GIT_BISECT_START_USAGE,
54
- BUILTIN_GIT_BISECT_STATE_USAGE,
57
+ BUILTIN_GIT_BISECT_BAD_USAGE,
58
+ BUILTIN_GIT_BISECT_GOOD_USAGE,
59
BUILTIN_GIT_BISECT_TERMS_USAGE,
60
BUILTIN_GIT_BISECT_SKIP_USAGE,
61
BUILTIN_GIT_BISECT_NEXT_USAGE,
@@ -60,6 +64,7 @@ static const char * const git_bisect_usage[] = {
64
BUILTIN_GIT_BISECT_REPLAY_USAGE,
65
BUILTIN_GIT_BISECT_LOG_USAGE,
66
BUILTIN_GIT_BISECT_RUN_USAGE,
67
+ BUILTIN_GIT_BISECT_HELP_USAGE,
68
NULL
69
};
70
t/t0450/adoc-help-mismatches
-1
@@ -2,7 +2,6 @@ add
2
am
3
apply
4
archive
5
-bisect
5
blame
6
branch
7
check-ref-format