doc: git-bisect to synopsis
cover doc: git-bisect to synopsis
Update the format of bisect. This one was less involved than git-blame.
Should I be changing any code blocks to [synopsis] as well?
There might also be formatting changes desired among the "Bisect run" exit codes.
Michael Lyons (1):
doc: git-bisect: convert to new doc format
Documentation/git-bisect.adoc | 67 ++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 33 deletions(-)
Signature · 1 line
2.47.3
PATCH 1/1 doc: git-bisect: convert to new doc format
- Change placeholders to glossary terms
- Refer to placeholders in prose
- Delimit runnable commands and CLI args with backticks
- Link internal heading
--- Documentation/git-bisect.adoc | 67 ++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 33 deletions(-)
Documentation/git-bisect.adoc +34 -33
@@ -8,20 +8,20 @@ git-bisect - Use binary search to find the commit that introduced a bug SYNOPSIS -------- -[verse] -'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 +[synopsis] +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>) [<commit>] +git bisect (good|old|<term-old>) [<commit>...] +git bisect terms [--term-(good|old) | --term-(bad|new)] +git bisect skip [(<commit>|<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 -----------
@@ -38,8 +38,8 @@ In fact, `git bisect` can be used to find the commit that changed *any* property of your project; e.g., the commit that fixed a bug, or the commit that caused a benchmark's performance to improve. To support this more general usage, the terms "old" and "new" can be used -in place of "good" and "bad", or you can choose your own terms. See -section "Alternate terms" below for more information. +in place of "good" and "bad", or you can choose your own terms. See the +<<alternate-terms,Alternate terms>> section below for more information. Basic bisect commands: start, bad, good ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -116,6 +116,7 @@ bad revision, while `git bisect reset HEAD` will leave you on the current bisection commit and avoid switching commits at all. +[[alternate-terms]] Alternate terms ~~~~~~~~~~~~~~~
@@ -144,13 +145,13 @@ bisect start` without commits as argument and then run the following commands to add the commits: ------------------------------------------------ -git bisect old [<rev>] +git bisect old [<commit>] ------------------------------------------------ to indicate that a commit was before the sought change, or ------------------------------------------------ -git bisect new [<rev>...] +git bisect new [<commit>...] ------------------------------------------------ to indicate that it was after.
@@ -208,7 +209,7 @@ Git detects a graphical environment through various environment variables: `MSYSTEM`, which is set under Msys2 and Git for Windows. `SECURITYSESSIONID`, which may be set on macOS in interactive desktop sessions. -If none of these environment variables is set, 'git log' is used instead. +If none of these environment variables is set, `git log` is used instead. You can also give command-line options such as `-p` and `--stat`. ------------
@@ -308,8 +309,8 @@ by checking out a different revision. Cutting down bisection by giving more parameters to bisect start ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can further cut down the number of trials, if you know what part of -the tree is involved in the problem you are tracking down, by specifying +If you know what part of the tree is involved in the problem you are +tracking down, you can further cut down the number of trials by specifying pathspec parameters when issuing the `bisect start` command: ------------
@@ -333,12 +334,12 @@ If you have a script that can tell if the current source code is good or bad, you can bisect by issuing the command: ------------ -$ git bisect run my_script arguments +$ git bisect run <my_script> <arguments> ------------ -Note that the script (`my_script` in the above example) should exit -with code 0 if the current source code is good/old, and exit with a -code between 1 and 127 (inclusive), except 125, if the current source +Note that the script (`<my_script> <arguments>` in the above example) +should exit with code 0 if the current source code is good/old, and exit +with a code between 1 and 127 (inclusive), except 125, if the current source code is bad/new. Any other exit code will abort the bisect process. It should be noted
@@ -355,22 +356,22 @@ details do not matter, as they are normal errors in the script, as far as `bisect run` is concerned). You may often find that during a bisect session you want to have -temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a +temporary modifications (e.g. `s/#define DEBUG 0/#define DEBUG 1/` in a header file, or "revision that does not have this commit needs this patch applied to work around another problem this bisection is not interested in") applied to the revision being tested. -To cope with such a situation, after the inner 'git bisect' finds the +To cope with such a situation, after the inner `git bisect` finds the next revision to test, the script can apply the patch before compiling, run the real test, and afterwards decide if the revision (possibly with the needed patch) passed the test and then -rewind the tree to the pristine state. Finally the script should exit +rewind the tree to the pristine state. Finally, the script should exit with the status of the real test to let the `git bisect run` command loop determine the eventual outcome of the bisect session. OPTIONS ------- ---no-checkout:: +`--no-checkout`:: + Do not checkout the new working tree at each iteration of the bisection process. Instead just update the reference named `BISECT_HEAD` to make
@@ -381,7 +382,7 @@ does not require a checked out tree. + If the repository is bare, `--no-checkout` is assumed. ---first-parent:: +`--first-parent`:: + Follow only the first parent commit upon seeing a merge commit. +
@@ -491,9 +492,9 @@ $ git bisect run sh -c ' $ git bisect reset # quit the bisect session ------------ + -In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that -has at least one parent whose reachable graph is fully traversable in the sense -required by 'git pack objects'. +In this case, when `git bisect run` finishes, bisect/bad will refer to a +commit that has at least one parent whose reachable graph is fully +traversable in the sense required by `git pack objects`. * Look for a fix instead of a regression in the code +
Signature · 1 line
2.47.3
Re: [PATCH 1/1] doc: git-bisect: convert to new doc format
Quoted 1 line · Michael Lyons
- Change placeholders to glossary terms
I see you changed <rev> to <commit> and I guess the point above is a reference to that change, but I cannot be sure if (1) there are things other than <rev> that you changed for the same reason, and
(2) if "glossary has it" is the reason for the change (we have "revision" in there, and it is widely known that "rev" is an abbreviation for it in the context of these documentation pages).
You can rephrase the above, perhaps like
Some parameters are described with placeholders with less common words, which is unnecessarily harder to understand by new readers. Use <commit> instead of <rev>.
to avoid the problem, if <rev> -> <commit> is the only change for this reason. If there are more words you addressed, perhaps you can replace the last sentence.
Quoted 3 lines
- Refer to placeholders in prose
- Delimit runnable commands and CLI args with backticks
- Link internal heading
The same comments may apply to these three.
Thanks.
Re: [PATCH 1/1] doc: git-bisect: convert to new doc format
In reply to Michael LyonsDocumentation/git-bisect.adoc git-bisect - Use binary search to find the commit that
Quoted 15 lines · On Sunday, 11 January 2026 21:42:48 CET Michael Lyons wrote:
- Change placeholders to glossary terms
- Refer to placeholders in prose
- Delimit runnable commands and CLI args with backticks
- Link internal headingSigned-off-by Michael Lyons <[email protected]>--- Documentation/git-bisect.adoc | 67 ++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 33 deletions(-)Documentation/git-bisect.adoc +0
-0@@ -8,20 +8,20 @@ git-bisect - Use binary search to find the commit that
introduced
Quoted 6 lines
a bug
SYNOPSIS
--------
-[verse]
-'git bisect' start [--term-(bad|new)=<term-new> --term-(good|old)=<term-
old>]
Documentation/git-bisect.adoc
Quoted 1 line
Documentation/git-bisect.adoc +0
-1- [--no-checkout] [--first-parent] [<bad> [<good>...]]
[--] [<pathspec>...]
Quoted 12 lines
-'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
+[synopsis]
Documentation/git-bisect.adoc
Quoted 2 lines
Documentation/git-bisect.adoc +2
-0+git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>] + [--no-checkout] [--first-parent] [<bad> [<good>...]] [--]
[<pathspec>...]
Documentation/git-bisect.adoc In fact, `git bisect` can be used to find the commit that
Quoted 15 lines
Documentation/git-bisect.adoc +11
-0+git bisect (bad|new|<term-new>) [<commit>] +git bisect (good|old|<term-old>) [<commit>...] +git bisect terms [--term-(good|old) | --term-(bad|new)] +git bisect skip [(<commit>|<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 -----------@@ -38,8 +38,8 @@ In fact, `git bisect` can be used to find the commit that
changed
Documentation/git-bisect.adoc bad revision, while `git bisect reset HEAD` will leave
Quoted 11 lines
Documentation/git-bisect.adoc +2
-2*any* property of your project; e.g., the commit that fixed a bug, or the commit that caused a benchmark's performance to improve. To support this more general usage, the terms "old" and "new" can be used -in place of "good" and "bad", or you can choose your own terms. See -section "Alternate terms" below for more information. +in place of "good" and "bad", or you can choose your own terms. See the +<<alternate-terms,Alternate terms>> section below for more information. Basic bisect commands: start, bad, good ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~@@ -116,6 +116,7 @@ bad revision, while `git bisect reset HEAD` will leave
you on
Documentation/git-bisect.adoc bisect start` without commits as argument and then run
Quoted 8 lines
the current bisection commit and avoid switching commits at all.
+[[alternate-terms]]
Alternate terms
~~~~~~~~~~~~~~~Documentation/git-bisect.adoc +0
-0@@ -144,13 +145,13 @@ bisect start` without commits as argument and then run
the
Documentation/git-bisect.adoc Git detects a graphical environment through various
Quoted 16 lines
following commands to add the commits:
------------------------------------------------
Documentation/git-bisect.adoc +2
-2-git bisect old [<rev>] +git bisect old [<commit>] ------------------------------------------------ to indicate that a commit was before the sought change, or ------------------------------------------------ -git bisect new [<rev>...] +git bisect new [<commit>...] ------------------------------------------------ to indicate that it was after.@@ -208,7 +209,7 @@ Git detects a graphical environment through various
environment
Quoted 2 lines
variables:
MSYSTEM, which is set under Msys2 and Git for Windows.
SECURITYSESSIONID, which may be set on macOS in interactive desktop
sessions.
Documentation/git-bisect.adoc If you have a script that can tell if the current
Quoted 18 lines
Documentation/git-bisect.adoc +3
-3-If none of these environment variables is set, 'git log' is used instead. +If none of these environment variables is set, `git log` is used instead. You can also give command-line options such as `-p` and `--stat`. ------------@@ -308,8 +309,8 @@ by checking out a different revision. Cutting down bisection by giving more parameters to bisect start ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can further cut down the number of trials, if you know what part of -the tree is involved in the problem you are tracking down, by specifying +If you know what part of the tree is involved in the problem you are +tracking down, you can further cut down the number of trials by specifying pathspec parameters when issuing the `bisect start` command: ------------@@ -333,12 +334,12 @@ If you have a script that can tell if the current
source code
Quoted 6 lines
is good or bad, you can bisect by issuing the command:
------------
-$ git bisect runmy_scriptarguments
+$ git bisect run <my_script> <arguments>
------------
Here, if you want to use to use the synopsis formatting, you may replace the verbatim block with a [synopsis] one:
[synopsis]
$ git bisect run <my_script> <arguments>
Otherwise, LGTM
Thanks.
Re: [PATCH 1/1] doc: git-bisect: convert to new doc format
Quoted 11 lines · Jean-Noël AVILA
Quoted 4 lines
------------
-$ git bisect runmy_scriptarguments
+$ git bisect run <my_script> <arguments>
------------Here, if you want to use to use the synopsis formatting, you may replace the verbatim block with a [synopsis] one:
[synopsis]
$ git bisect run <my_script> <arguments>
Can you add a bit to "if you _want_ to use" above? What's the pros-and-cons of doing so or leaving it as the way it is written in the patch? That would help people on the same page when they decide if they want to use the [synopsis], preferring over the verbatim block.
Quoted 4 lines
Otherwise, LGTM
Thanks.
Thanks for a review.
Re: [PATCH 1/1] doc: git-bisect: convert to new doc format
Le 13 janvier 2026 13:54:23 GMT+01:00, Junio C Hamano <[email protected]> a écrit :
Quoted 14 lines
Quoted 11 lines · Jean-Noël AVILA
Quoted 4 lines
------------
-$ git bisect runmy_scriptarguments
+$ git bisect run <my_script> <arguments>
------------Here, if you want to use to use the synopsis formatting, you may replace the verbatim block with a [synopsis] one:
[synopsis]
$ git bisect run <my_script> <arguments>
Quoted 6 lines
Can you add a bit to "if you _want_ to use" above? What's the pros-and-cons of doing so or leaving it as the way it is written in the patch? That would help people on the same page when they decide if they want to use the [synopsis], preferring over the verbatim block.
The rationale is simple: the patch is changing the mode of this section from a verbatim instance of example to a synopsis model of command. I'm not settled on whether this is a good move. What is sure though is that when writing in synopsis grammar, it is better to switch to synopsis style, in order to maintain a consistent output and allow clearer and more direct explanations.