# [BUG] git-bisect man page description of terms command doesn't mention old/new support

11 messages from 2023-12-09 to 2024-02-09. Participants: Britton Kerin, Junio C Hamano, Matthieu Moy, Kristoffer Haugsbakk, Jean-Noël Avila, Christian Couder.
Thread: https://gitlist.dev/t/60598

## Britton Kerin, 2023-12-09 11:58

Subject: [BUG] git-bisect man page description of terms command doesn't mention old/new support
Message-ID: <CAC4O8c9ieZC4SBJf54ZuTfAvnkhGuDaibBQ-m9Zw_n5VhUFPag@mail.gmail.com>
URL: https://gitlist.dev/e/CAC4O8c9ieZC4SBJf54ZuTfAvnkhGuDaibBQ-m9Zw_n5VhUFPag%40mail.gmail.com

```
It's a very small issue but it seems that git bisect terms does
support --term-old and --term-new options, however the man page says:

    git bisect terms [--term-good | --term-bad]

The description for the start subcommand does document the support for
the more general terms correctly:

    git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]

so maybe it's worth fixing the git bisect terms documentation.

Britton

```

## Junio C Hamano, 2023-12-09 16:13

Subject: Re* [BUG] git-bisect man page description of terms command doesn't mention old/new support
Message-ID: <xmqqzfyjmk02.fsf@gitster.g>
URL: https://gitlist.dev/e/xmqqzfyjmk02.fsf%40gitster.g
In-Reply-To: <CAC4O8c9ieZC4SBJf54ZuTfAvnkhGuDaibBQ-m9Zw_n5VhUFPag@mail.gmail.com>

```
Britton Kerin <britton.kerin@gmail.com> writes:

> It's a very small issue but it seems that git bisect terms does
> support --term-old and --term-new options, however the man page says:
>
>     git bisect terms [--term-good | --term-bad]
>
> The description for the start subcommand does document the support for
> the more general terms correctly:
>
>     git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]
>
> so maybe it's worth fixing the git bisect terms documentation.

In the description, we see

    To get a reminder of the currently used terms, use

    ------------------------------------------------
    git bisect terms
    ------------------------------------------------

    You can get just the old (respectively new) term with `git bisect terms
    --term-old` or `git bisect terms --term-good`.

so you could read that

	git bisect terms --term-good
	git bisect terms --term-old

are the same thing, and when you squint your eyes, you can probably
guess that

	git bisect terms --term-bad
	git bisect terms --term-new

are the same.  But I agree that the documentation should not force
you to guess.  This dates back to 21b55e33 (bisect: add 'git bisect
terms' to view the current terms, 2015-06-29).

------------ >8 ------------ >8 ------------ >8 ------------
Subject: [PATCH] bisect: document "terms" subcommand more fully

The documentation for "git bisect terms", although it did not hide
any information, was a bit incomplete and forced readers to fill in
the blanks to get the complete picture.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-bisect.txt | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git c/Documentation/git-bisect.txt w/Documentation/git-bisect.txt
index 191b4a42b6..16daa09c78 100644
--- c/Documentation/git-bisect.txt
+++ w/Documentation/git-bisect.txt
@@ -20,7 +20,7 @@ on the subcommand:
 		  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...]
  git bisect (bad|new|<term-new>) [<rev>]
  git bisect (good|old|<term-old>) [<rev>...]
- git bisect terms [--term-good | --term-bad]
+ git bisect terms [--term-(good|old) | --term-(bad|new)]
  git bisect skip [(<rev>|<range>)...]
  git bisect reset [<commit>]
  git bisect (visualize|view)
@@ -165,8 +165,10 @@ To get a reminder of the currently used terms, use
 git bisect terms
 ------------------------------------------------
 
-You can get just the old (respectively new) term with `git bisect terms
---term-old` or `git bisect terms --term-good`.
+You can get just the old term with `git bisect terms --term-old`
+or `git bisect terms --term-good`; `git bisect terms --term-new`
+and `git bisect terms --term-bad` can be used to learn how to call
+the commits more recent than the sought change.
 
 If you would like to use your own terms instead of "bad"/"good" or
 "new"/"old", you can choose any names you like (except existing bisect


```

## Matthieu Moy, 2023-12-11 12:34

Subject: Re: Re* [BUG] git-bisect man page description of terms command doesn't mention old/new support
Message-ID: <24a42fa6-7bc4-4a3b-8bf4-a0ef85dc457a@matthieu-moy.fr>
URL: https://gitlist.dev/e/24a42fa6-7bc4-4a3b-8bf4-a0ef85dc457a%40matthieu-moy.fr
In-Reply-To: <xmqqzfyjmk02.fsf@gitster.g>

```
On 12/9/23 17:13, Junio C Hamano wrote:

> so you could read that
> 
> 	git bisect terms --term-good
> 	git bisect terms --term-old
> 
> are the same thing, and when you squint your eyes, you can probably
> guess that
> 
> 	git bisect terms --term-bad
> 	git bisect terms --term-new
> 
> are the same.  But I agree that the documentation should not force
> you to guess.

Agreed.
> --- c/Documentation/git-bisect.txt
> +++ w/Documentation/git-bisect.txt
> @@ -20,7 +20,7 @@ on the subcommand:
>   		  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...]
>    git bisect (bad|new|<term-new>) [<rev>]
>    git bisect (good|old|<term-old>) [<rev>...]
> - git bisect terms [--term-good | --term-bad]
> + git bisect terms [--term-(good|old) | --term-(bad|new)]

Nit: just above we have the description for `bisect start` saying:

--term-{new,bad}=<term> --term-{old,good}=<term>

it probably makes sense to make both homogeneous (start with the same 
alternative, and make the {...,...} vs (...|...) notations consistent. 
The (...|...) notation seems the most common).

In any case, the patch looks good to me, thanks.

-- 
Matthieu Moy
https://matthieu-moy.fr/

```

## Junio C Hamano, 2023-12-11 15:05

Subject: Re: Re* [BUG] git-bisect man page description of terms command doesn't mention old/new support
Message-ID: <xmqqil54vkya.fsf@gitster.g>
URL: https://gitlist.dev/e/xmqqil54vkya.fsf%40gitster.g
In-Reply-To: <24a42fa6-7bc4-4a3b-8bf4-a0ef85dc457a@matthieu-moy.fr>

```
Matthieu Moy <git@matthieu-moy.fr> writes:

> Nit: just above we have the description for `bisect start` saying:
>
> --term-{new,bad}=<term> --term-{old,good}=<term>
>
> it probably makes sense to make both homogeneous (start with the same
> alternative, and make the {...,...} vs (...|...) notations
> consistent. The (...|...) notation seems the most common).

Thanks for noticing; I think it has already been fixed a few months
ago, but apparently what I sent predates 3f02785d (doc/git-bisect:
clarify `git bisect run` syntax, 2023-10-23).  So when the patch
gets merged, it will fix itself ;-)

> In any case, the patch looks good to me, thanks.

Thanks.

```

## Junio C Hamano, 2024-02-07 21:44

Subject: [PATCH 0/2] minute "git bisect" doc updates
Message-ID: <20240207214436.538586-1-gitster@pobox.com>
URL: https://gitlist.dev/e/20240207214436.538586-1-gitster%40pobox.com
In-Reply-To: <24a42fa6-7bc4-4a3b-8bf4-a0ef85dc457a@matthieu-moy.fr>

```
"git bisect" documentation was a bit sketchy on alternative keywords
"new" and "old", that are used to signal if a command is from the
part of the history that is newer or older than "a significant
event" the bisection is trying to find.  Here are two small patches
that improves the documentation.

I am trying to flush my "stalled topics" queue.  Here is a small and
(hopefully) easy-to-finish one.

The original discussion was from early December 2023 and can be
found at

https://lore.kernel.org/git/CAC4O8c9ieZC4SBJf54ZuTfAvnkhGuDaibBQ-m9Zw_n5VhUFPag@mail.gmail.com/



Junio C Hamano (2):
  bisect: document "terms" subcommand more fully
  bisect: document command line arguments for "bisect start"

 Documentation/git-bisect.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

-- 
2.43.0-561-g235986be82


```

## Junio C Hamano, 2024-02-07 21:44

Subject: [PATCH 1/2] bisect: document "terms" subcommand more fully
Message-ID: <20240207214436.538586-2-gitster@pobox.com>
URL: https://gitlist.dev/e/20240207214436.538586-2-gitster%40pobox.com
In-Reply-To: <20240207214436.538586-1-gitster@pobox.com>

```
The documentation for "git bisect terms", although it did not hide
any information, was a bit incomplete and forced readers to fill in
the blanks to get the complete picture.

Acked-by: Matthieu Moy <git@matthieu-moy.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-bisect.txt | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index fbb39fbdf5..3d813f9c77 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -20,7 +20,7 @@ on the subcommand:
 		  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...]
  git bisect (bad|new|<term-new>) [<rev>]
  git bisect (good|old|<term-old>) [<rev>...]
- git bisect terms [--term-good | --term-bad]
+ git bisect terms [--term-(good|old) | --term-(bad|new)]
  git bisect skip [(<rev>|<range>)...]
  git bisect reset [<commit>]
  git bisect (visualize|view)
@@ -165,8 +165,10 @@ To get a reminder of the currently used terms, use
 git bisect terms
 ------------------------------------------------
 
-You can get just the old (respectively new) term with `git bisect terms
---term-old` or `git bisect terms --term-good`.
+You can get just the old term with `git bisect terms --term-old`
+or `git bisect terms --term-good`; `git bisect terms --term-new`
+and `git bisect terms --term-bad` can be used to learn how to call
+the commits more recent than the sought change.
 
 If you would like to use your own terms instead of "bad"/"good" or
 "new"/"old", you can choose any names you like (except existing bisect
-- 
2.43.0-561-g235986be82


```

## Junio C Hamano, 2024-02-07 21:44

Subject: [PATCH 2/2] bisect: document command line arguments for "bisect start"
Message-ID: <20240207214436.538586-3-gitster@pobox.com>
URL: https://gitlist.dev/e/20240207214436.538586-3-gitster%40pobox.com
In-Reply-To: <20240207214436.538586-1-gitster@pobox.com>

```
The syntax commonly used for alternatives is --opt-(a|b), not
--opt-{a,b}.

List bad/new and good/old consistently in this order, to be
consistent with the description for "git bisect terms".  Clarify
<term> to either <term-old> or <term-new> to make them consistent
with the description of "git bisect (good|bad)" subcommands.

Suggested-by: Matthieu Moy <git@matthieu-moy.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-bisect.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index 3d813f9c77..73f889b97b 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -16,7 +16,7 @@ DESCRIPTION
 The command takes various subcommands, and different options depending
 on the subcommand:
 
- git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]
+ git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
 		  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...]
  git bisect (bad|new|<term-new>) [<rev>]
  git bisect (good|old|<term-old>) [<rev>...]
-- 
2.43.0-561-g235986be82


```

## Kristoffer Haugsbakk, 2024-02-08 06:36

Subject: Re: [PATCH 1/2] bisect: document "terms" subcommand more fully
Message-ID: <a8e67945-153b-43bb-b1b0-ea24fa786097@app.fastmail.com>
URL: https://gitlist.dev/e/a8e67945-153b-43bb-b1b0-ea24fa786097%40app.fastmail.com
In-Reply-To: <20240207214436.538586-2-gitster@pobox.com>

```
On Wed, Feb 7, 2024, at 22:44, Junio C Hamano wrote:
> The documentation for "git bisect terms", although it did not hide
> any information, was a bit incomplete and forced readers to fill in
> the blanks to get the complete picture.
>
> Acked-by: Matthieu Moy <git@matthieu-moy.fr>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---

Past tense? How about:

    The documentation for "git bisect terms"---although it does not hide
    any information---is a bit incomplete and forces readers to fill in
    the blanks to get the complete picture.

-- 
Kristoffer Haugsbakk


```

## Jean-Noël Avila, 2024-02-08 16:18

Subject: Re: [PATCH 2/2] bisect: document command line arguments for "bisect start"
Message-ID: <21ec33d4-4036-4763-9117-fbbdca1e2273@gmail.com>
URL: https://gitlist.dev/e/21ec33d4-4036-4763-9117-fbbdca1e2273%40gmail.com
In-Reply-To: <20240207214436.538586-3-gitster@pobox.com>

```
Le 07/02/2024 à 22:44, Junio C Hamano a écrit :
> The syntax commonly used for alternatives is --opt-(a|b), not
> --opt-{a,b}.
>
> List bad/new and good/old consistently in this order, to be
> consistent with the description for "git bisect terms".  Clarify
> <term> to either <term-old> or <term-new> to make them consistent
> with the description of "git bisect (good|bad)" subcommands.
>
> Suggested-by: Matthieu Moy <git@matthieu-moy.fr>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>   Documentation/git-bisect.txt | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
> index 3d813f9c77..73f889b97b 100644
> --- a/Documentation/git-bisect.txt
> +++ b/Documentation/git-bisect.txt
> @@ -16,7 +16,7 @@ DESCRIPTION
>   The command takes various subcommands, and different options depending
>   on the subcommand:
>   
> - git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>]
> + git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
>   		  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...]
>    git bisect (bad|new|<term-new>) [<rev>]
>    git bisect (good|old|<term-old>) [<rev>...]


LGTM


```

## Junio C Hamano, 2024-02-08 16:48

Subject: Re: [PATCH 1/2] bisect: document "terms" subcommand more fully
Message-ID: <xmqqil2yq4vr.fsf@gitster.g>
URL: https://gitlist.dev/e/xmqqil2yq4vr.fsf%40gitster.g
In-Reply-To: <a8e67945-153b-43bb-b1b0-ea24fa786097@app.fastmail.com>

```
"Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:

> On Wed, Feb 7, 2024, at 22:44, Junio C Hamano wrote:
>> The documentation for "git bisect terms", although it did not hide
>> any information, was a bit incomplete and forced readers to fill in
>> the blanks to get the complete picture.
>>
>> Acked-by: Matthieu Moy <git@matthieu-moy.fr>
>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>> ---
>
> Past tense? How about:
>
>     The documentation for "git bisect terms"---although it does not hide
>     any information---is a bit incomplete and forces readers to fill in
>     the blanks to get the complete picture.

Right.
Thanks.

```

## Christian Couder, 2024-02-09 09:39

Subject: Re: [PATCH 0/2] minute "git bisect" doc updates
Message-ID: <CAP8UFD0eNvMrUDshZBfrE+3WbRWGr6oa-o8Q4ecrLcY1-vhyFQ@mail.gmail.com>
URL: https://gitlist.dev/e/CAP8UFD0eNvMrUDshZBfrE%2B3WbRWGr6oa-o8Q4ecrLcY1-vhyFQ%40mail.gmail.com
In-Reply-To: <20240207214436.538586-1-gitster@pobox.com>

```
On Wed, Feb 7, 2024 at 11:13 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "git bisect" documentation was a bit sketchy on alternative keywords
> "new" and "old", that are used to signal if a command is from the
> part of the history that is newer or older than "a significant
> event" the bisection is trying to find.  Here are two small patches
> that improves the documentation.
>
> I am trying to flush my "stalled topics" queue.  Here is a small and
> (hopefully) easy-to-finish one.
>
> The original discussion was from early December 2023 and can be
> found at
>
> https://lore.kernel.org/git/CAC4O8c9ieZC4SBJf54ZuTfAvnkhGuDaibBQ-m9Zw_n5VhUFPag@mail.gmail.com/
>
> Junio C Hamano (2):
>   bisect: document "terms" subcommand more fully
>   bisect: document command line arguments for "bisect start"

Both patches look good to me. You can add my "Reviewed-by:".

Thanks!

```