[PATCH 0/1] doc: git-bisect to synopsis

[PATCH 0/1] doc: git-bisect to synopsis

[Michael Lyons]

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

-- 
2.47.3

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

[Michael Lyons]

- Change placeholders to glossary terms
- Refer to placeholders in prose
- Delimit runnable commands and CLI args with backticks
- Link internal heading

Signed-off-by: Michael Lyons <git@michael.lyo.nz>
---
 Documentation/git-bisect.adoc | 67 ++++++++++++++++++-----------------
 1 file changed, 34 insertions(+), 33 deletions(-)

diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc
index b0078dda0e..65fec9fd29 100644
--- a/Documentation/git-bisect.adoc
+++ b/Documentation/git-bisect.adoc
@@ -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
 +
-- 
2.47.3

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

[Junio C Hamano]

Michael Lyons <git@michael.lyo.nz> writes:

> - 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.


> - 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

[Jean-Noël AVILA]

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
> 
> Signed-off-by: Michael Lyons <git@michael.lyo.nz>
> ---
>  Documentation/git-bisect.adoc | 67 ++++++++++++++++++-----------------
>  1 file changed, 34 insertions(+), 33 deletions(-)
> 
> diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc
> index b0078dda0e..65fec9fd29 100644
> --- a/Documentation/git-bisect.adoc
> +++ b/Documentation/git-bisect.adoc
> @@ -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>
>  ------------

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

[Junio C Hamano]

Jean-Noël AVILA <jn.avila@free.fr> writes:

>>  ------------
>> -$ 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.

>
> Otherwise, LGTM
>
> Thanks.

Thanks for a review.

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

[Jean-Noël Avila]

Le 13 janvier 2026 13:54:23 GMT+01:00, Junio C Hamano <gitster@pobox.com> a écrit :
>Jean-Noël AVILA <jn.avila@free.fr> writes:
>
>>>  ------------
>>> -$ 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.
>

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.