doc: convert git-bisect to synopsis style
Convert Documentation/git-bisect.adoc to the modern synopsis style. - Replace [verse] with [synopsis] in the SYNOPSIS block - Remove single quotes around command names in the synopsis - Use backticks for inline commands, options, refs, and special values - Apply [synopsis] attribute to in-body command-form code blocks - Format OPTIONS entries with backtick-quoted terms and direct - Add synopsis-style formatting to listing blocks - Format man page references as `command`(N) Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jean-Noël Avila committed
May 25, 2026 at 10:28 UTC
50cd5219d2b63f4896a3d142f83fadf8e47a6c3b
2 files changed
+48
-48
Documentation/asciidoc.conf.in
+6
@@ -84,6 +84,9 @@ ifdef::doctype-manpage[]
84
[blockdef-open]
85
synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'"
86
87
+[blockdef-listing]
88
+synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'"
89
+
90
[paradef-default]
91
synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'"
92
endif::doctype-manpage[]
@@ -93,6 +96,9 @@ ifdef::backend-xhtml11[]
96
[blockdef-open]
97
synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'"
98
99
+[blockdef-listing]
100
+synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'"
101
+
102
[paradef-default]
103
synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'"
104
endif::backend-xhtml11[]
Documentation/git-bisect.adoc
+42
-48
@@ -8,20 +8,20 @@ git-bisect - Use binary search to find the commit that introduced a bug
8
9
SYNOPSIS
10
--------
11
-[verse]
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
11
+[synopsis]
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
-----------
@@ -94,7 +94,7 @@ Bisect reset
94
~~~~~~~~~~~~
95
96
After a bisect session, to clean up the bisection state and return to
97
-the original HEAD, issue the following command:
97
+the original `HEAD`, issue the following command:
98
99
------------------------------------------------
100
$ git bisect reset
@@ -107,9 +107,8 @@ that, as it cleans up the old bisection state.)
107
With an optional argument, you can return to a different commit
108
instead:
109
110
-------------------------------------------------
110
+[synopsis]
111
$ git bisect reset <commit>
112
-------------------------------------------------
112
113
For example, `git bisect reset bisect/bad` will check out the first
114
bad revision, while `git bisect reset HEAD` will leave you on the
@@ -143,23 +142,20 @@ To use "old" and "new" instead of "good" and bad, you must run `git
142
bisect start` without commits as argument and then run the following
143
commands to add the commits:
144
146
-------------------------------------------------
145
+[synopsis]
146
git bisect old [<rev>]
148
-------------------------------------------------
147
148
to indicate that a commit was before the sought change, or
149
152
-------------------------------------------------
150
+[synopsis]
151
git bisect new [<rev>...]
154
-------------------------------------------------
152
153
to indicate that it was after.
154
155
To get a reminder of the currently used terms, use
156
160
-------------------------------------------------
157
+[synopsis]
158
git bisect terms
162
-------------------------------------------------
159
160
You can get just the old term with `git bisect terms --term-old`
161
or `git bisect terms --term-good`; `git bisect terms --term-new`
@@ -171,9 +167,8 @@ If you would like to use your own terms instead of "bad"/"good" or
167
subcommands like `reset`, `start`, ...) by starting the
168
bisection using
169
174
-------------------------------------------------
170
+[synopsis]
171
git bisect start --term-old <term-old> --term-new <term-new>
176
-------------------------------------------------
172
173
For example, if you are looking for a commit that introduced a
174
performance regression, you might use
@@ -194,7 +189,7 @@ of `git bisect good` and `git bisect bad` to mark commits.
189
Bisect visualize/view
190
~~~~~~~~~~~~~~~~~~~~~
191
197
-To see the currently remaining suspects in 'gitk', issue the following
192
+To see the currently remaining suspects in `gitk`, issue the following
193
command during the bisection process (the subcommand `view` can be used
194
as an alternative to `visualize`):
195
@@ -203,12 +198,13 @@ $ git bisect visualize
198
------------
199
200
Git detects a graphical environment through various environment variables:
206
-`DISPLAY`, which is set in X Window System environments on Unix systems.
207
-`SESSIONNAME`, which is set under Cygwin in interactive desktop sessions.
208
-`MSYSTEM`, which is set under Msys2 and Git for Windows.
209
-`SECURITYSESSIONID`, which may be set on macOS in interactive desktop sessions.
201
211
-If none of these environment variables is set, 'git log' is used instead.
202
+`DISPLAY`:: which is set in X Window System environments on Unix systems.
203
+`SESSIONNAME`:: which is set under Cygwin in interactive desktop sessions.
204
+`MSYSTEM`:: which is set under Msys2 and Git for Windows.
205
+`SECURITYSESSIONID`:: which may be set on macOS in interactive desktop sessions.
206
+
207
+If none of these environment variables is set, `git log` is used instead.
208
You can also give command-line options such as `-p` and `--stat`.
209
210
------------
@@ -342,8 +338,8 @@ code between 1 and 127 (inclusive), except 125, if the current source
338
code is bad/new.
339
340
Any other exit code will abort the bisect process. It should be noted
345
-that a program that terminates via `exit(-1)` leaves $? = 255, (see the
346
-exit(3) manual page), as the value is chopped with `& 0377`.
341
+that a program that terminates via `exit(-1)` leaves `$?` = 255, (see the
342
+`exit`(3) manual page), as the value is chopped with `& 0377`.
343
344
The special exit code 125 should be used when the current source code
345
cannot be tested. If the script exits with this code, the current
@@ -355,12 +351,12 @@ details do not matter, as they are normal errors in the script, as far as
351
`bisect run` is concerned).
352
353
You may often find that during a bisect session you want to have
358
-temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a
354
+temporary modifications (e.g. `s/#define DEBUG 0/#define DEBUG 1/` in a
355
header file, or "revision that does not have this commit needs this
356
patch applied to work around another problem this bisection is not
357
interested in") applied to the revision being tested.
358
363
-To cope with such a situation, after the inner 'git bisect' finds the
359
+To cope with such a situation, after the inner `git bisect` finds the
360
next revision to test, the script can apply the patch
361
before compiling, run the real test, and afterwards decide if the
362
revision (possibly with the needed patch) passed the test and then
@@ -370,20 +366,18 @@ determine the eventual outcome of the bisect session.
366
367
OPTIONS
368
-------
373
---no-checkout::
374
-+
375
-Do not checkout the new working tree at each iteration of the bisection
376
-process. Instead just update the reference named `BISECT_HEAD` to make
377
-it point to the commit that should be tested.
369
+`--no-checkout`::
370
+ Do not checkout the new working tree at each iteration of the bisection
371
+ process. Instead just update the reference named `BISECT_HEAD` to make
372
+ it point to the commit that should be tested.
373
+
374
This option may be useful when the test you would perform in each step
375
does not require a checked out tree.
376
+
377
If the repository is bare, `--no-checkout` is assumed.
378
384
---first-parent::
385
-+
386
-Follow only the first parent commit upon seeing a merge commit.
379
+`--first-parent`::
380
+ Follow only the first parent commit upon seeing a merge commit.
381
+
382
In detecting regressions introduced through the merging of a branch, the merge
383
commit will be identified as introduction of the bug and its ancestors will be
@@ -395,7 +389,7 @@ branch contained broken or non-buildable commits, but the merge itself was OK.
389
EXAMPLES
390
--------
391
398
-* Automatically bisect a broken build between v1.2 and HEAD:
392
+* Automatically bisect a broken build between v1.2 and `HEAD`:
393
+
394
------------
395
$ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good
@@ -403,7 +397,7 @@ $ git bisect run make # "make" builds the app
397
$ git bisect reset # quit the bisect session
398
------------
399
406
-* Automatically bisect a test failure between origin and HEAD:
400
+* Automatically bisect a test failure between origin and `HEAD`:
401
+
402
------------
403
$ git bisect start HEAD origin -- # HEAD is bad, origin is good
@@ -430,7 +424,7 @@ and `exit 1` otherwise.
424
+
425
It is safer if both `test.sh` and `check_test_case.sh` are
426
outside the repository to prevent interactions between the bisect,
433
-make and test processes and the scripts.
427
+`make` and test processes and the scripts.
428
429
* Automatically bisect with temporary modifications (hot-fix):
430
+
@@ -491,9 +485,9 @@ $ git bisect run sh -c '
485
$ git bisect reset # quit the bisect session
486
------------
487
+
494
-In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that
488
+In this case, when `git bisect run` finishes, `bisect/bad` will refer to a commit that
489
has at least one parent whose reachable graph is fully traversable in the sense
496
-required by 'git pack objects'.
490
+required by `git pack-objects`.
491
492
* Look for a fix instead of a regression in the code
493
+