From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Mon, 12 Jan 2026 21:23:55 GMT
Subject: Re: [PATCH 1/1] doc: git-bisect: convert to new doc format
Message-ID: <4705928.LvFx2qVVIh@piment-oiseau>
In-Reply-To: <20260111204316.836446-2-git@michael.lyo.nz>

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.