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

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

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

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

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

Agreed.

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 <git@matthieu-moy.fr> writes:

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

Thanks.

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

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

On Wed, Feb 7, 2024, at 22:44, Junio C Hamano wrote:

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" <code@khaugsbakk.name> writes:

Right. Thanks.

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

Le 07/02/2024 à 22:44, Junio C Hamano a écrit :

LGTM

On Wed, Feb 7, 2024 at 11:13 PM Junio C Hamano <gitster@pobox.com> wrote:

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

Thanks!