Skip to contentSkip to conversation

doc: git-bisect to synopsis

PATCH In review Michael Lyons 3 participants 6 messages Jan 11 – Jan 13 Documentation

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index b0078dda0e..65fec9fd29 100644
@@ -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
#2 lore raw

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.

#3 lore raw

Re: [PATCH 1/1] doc: git-bisect: convert to new doc format

In reply to Michael Lyons

Documentation/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 heading

---
 Documentation/git-bisect.adoc | 67 ++++++++++++++++++-----------------
 1 file changed, 34 insertions(+), 33 deletions(-)
Documentation/git-bisect.adoc +0 -0
index b0078dda0e..65fec9fd29 100644
@@ -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 run my_script arguments
+$ 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.

#4 lore raw

Re: [PATCH 1/1] doc: git-bisect: convert to new doc format

Quoted 11 lines · Jean-Noël AVILA
Quoted 4 lines

------------
-$ git bisect run my_script arguments
+$ 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.

#5 lore raw

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 run my_script arguments
+$ 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.