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

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

[Britton Kerin]

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

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

[Junio C Hamano]

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

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

[Matthieu Moy]

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/

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

[Junio C Hamano]

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.

[PATCH 0/2] minute "git bisect" doc updates

[Junio C Hamano]

"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

[PATCH 1/2] bisect: document "terms" subcommand more fully

[Junio C Hamano]

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

[PATCH 2/2] bisect: document command line arguments for "bisect start"

[Junio C Hamano]

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

Re: [PATCH 1/2] bisect: document "terms" subcommand more fully

[Kristoffer Haugsbakk]

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

Re: [PATCH 2/2] bisect: document command line arguments for "bisect start"

[Jean-Noël Avila]

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

Re: [PATCH 1/2] bisect: document "terms" subcommand more fully

[Junio C Hamano]

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

Re: [PATCH 0/2] minute "git bisect" doc updates

[Christian Couder]

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!