Bug report: Documentation error in git-bisect man description

Bug report: Documentation error in git-bisect man description

[Manuel Ullmann]

Hi,

there is a mistake in the git-bisect description.
The second paragraph of it says ‘the terms "old" and "new" can be used
in place of "good" and "bad"’. So from a logical point of view the
description part stating the usage syntax should be:

git bisect (bad|good) [<rev>]
git bisect (old|new) [<rev>...]

instead of

git bisect (bad|new) [<rev>]
git bisect (good|old) [<rev>...]

Checked man page version of 2.11.0, but it is in my local 2.10.2 git as well.

Best regards,
Manuel

Re: Bug report: Documentation error in git-bisect man description

[Junio C Hamano]

Manuel Ullmann <ullman.alias@posteo.de> writes:

> Hi,
>
> there is a mistake in the git-bisect description.
> The second paragraph of it says ‘the terms "old" and "new" can be used
> in place of "good" and "bad"’. So from a logical point of view the
> description part stating the usage syntax should be:
>
> git bisect (bad|good) [<rev>]
> git bisect (old|new) [<rev>...]
>
> instead of
>
> git bisect (bad|new) [<rev>]
> git bisect (good|old) [<rev>...]
>
> Checked man page version of 2.11.0, but it is in my local 2.10.2 git as well.

Hmmm, I tend to agree, modulo a minor fix.

If the description were in a context inside a paragraph like this:

	When you want to tell 'git bisect' that a <rev> belongs to
	the newer half of the history, you say

		git bisect (bad|new) [<rev>]

	On the other hand, when you want to tell 'git bisect' that a
	<rev> belongs to the older half of the history, you can say

		git bisect (good|old) [<rev>]

then the pairing we see in the current text makes quite a lot of
sense.

But in the early part of the description section, listing the
information that logically belongs to the synopsis section, I think
the current one is misleading.  You are painting commits with two
colors, and if you are from the "older vs newer" school, you say
either 'old' or 'new' as the names of these two colors, and do not
use 'bad' or 'good'.  A line with "git bisect (old|new) [<rev>]" in
the list would make more sense.

Similarly, if you are from the "still good vs already bad" school,
you would either say 'good' or 'bad' so you would want to see a line
with "git bisect (good|bad) [<rev>]" in the list (not "bad|good" in
that order, but opposite).

Christian, am I talking nonsense?

Re: Bug report: Documentation error in git-bisect man description

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Manuel Ullmann <ullman.alias@posteo.de> writes:
>
> Hmmm, I tend to agree, modulo a minor fix.
>
> If the description were in a context inside a paragraph like this:
>
> 	When you want to tell 'git bisect' that a <rev> belongs to
> 	the newer half of the history, you say
>
> 		git bisect (bad|new) [<rev>]
>
> 	On the other hand, when you want to tell 'git bisect' that a
> 	<rev> belongs to the older half of the history, you can say
>
> 		git bisect (good|old) [<rev>]
>
> then the pairing we see in the current text makes quite a lot of
> sense.

Actually, the above is _exactly_ what was intended.  I misread the
current documentation when I made the comment, and I think that the
current one _IS_ correct.  The latter half of the above is not about
a single rev.  You can paint multiple commits with the "older half"
color, i.e.

	On the other hand, when you want to tell 'git bisect' that
	one or more <rev>s  belong to the older half of the history,
	you can say

		git bisect (good|old) [<rev>...]

In contrast, you can mark only one <rev> as newer (or "already
bad").  So pairing (bad|good) and (new|old) like you suggested
breaks the correctness of the command line description.

If (bad|new) and (good|old) bothers you because they may mislead the
readers to think bad is an opposite of new (and good is an opposite
of old), the only solution I can think of to that problem is to
expand these two lines into four and list them like this:

        git bisect bad [<rev>]
        git bisect good [<rev>...]
        git bisect new [<rev>]
        git bisect old [<rev>...]

Re: Bug report: Documentation error in git-bisect man description

[Manuel Ullmann]

I see. Thanks for the clarification. The pairing not being pairs of
opposites was indeed, what confused me. So that description was not
meant in the sense, that you use these pairs when working with bisect, but
instead they are ordered according to the argument possibilities.

Sorry for spreading confusion. I think the second paragraph should be
sufficient for documentation.

Best regards
Manuel
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Manuel Ullmann <ullman.alias@posteo.de> writes:
>>
>> Hmmm, I tend to agree, modulo a minor fix.
>>
>> If the description were in a context inside a paragraph like this:
>>
>> 	When you want to tell 'git bisect' that a <rev> belongs to
>> 	the newer half of the history, you say
>>
>> 		git bisect (bad|new) [<rev>]
>>
>> 	On the other hand, when you want to tell 'git bisect' that a
>> 	<rev> belongs to the older half of the history, you can say
>>
>> 		git bisect (good|old) [<rev>]
>>
>> then the pairing we see in the current text makes quite a lot of
>> sense.
>
> Actually, the above is _exactly_ what was intended.  I misread the
> current documentation when I made the comment, and I think that the
> current one _IS_ correct.  The latter half of the above is not about
> a single rev.  You can paint multiple commits with the "older half"
> color, i.e.
>
> 	On the other hand, when you want to tell 'git bisect' that
> 	one or more <rev>s  belong to the older half of the history,
> 	you can say
>
> 		git bisect (good|old) [<rev>...]
>
> In contrast, you can mark only one <rev> as newer (or "already
> bad").  So pairing (bad|good) and (new|old) like you suggested
> breaks the correctness of the command line description.
>
> If (bad|new) and (good|old) bothers you because they may mislead the
> readers to think bad is an opposite of new (and good is an opposite
> of old), the only solution I can think of to that problem is to
> expand these two lines into four and list them like this:
>
>         git bisect bad [<rev>]
>         git bisect good [<rev>...]
>         git bisect new [<rev>]
>         git bisect old [<rev>...]

Re: Bug report: Documentation error in git-bisect man description

[Christian Couder]

On Fri, Jan 13, 2017 at 12:42 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Manuel Ullmann <ullman.alias@posteo.de> writes:
>>
>> Hmmm, I tend to agree, modulo a minor fix.
>>
>> If the description were in a context inside a paragraph like this:
>>
>>       When you want to tell 'git bisect' that a <rev> belongs to
>>       the newer half of the history, you say
>>
>>               git bisect (bad|new) [<rev>]
>>
>>       On the other hand, when you want to tell 'git bisect' that a
>>       <rev> belongs to the older half of the history, you can say
>>
>>               git bisect (good|old) [<rev>]
>>
>> then the pairing we see in the current text makes quite a lot of
>> sense.
>
> Actually, the above is _exactly_ what was intended.  I misread the
> current documentation when I made the comment, and I think that the
> current one _IS_ correct.  The latter half of the above is not about
> a single rev.  You can paint multiple commits with the "older half"
> color, i.e.
>
>         On the other hand, when you want to tell 'git bisect' that
>         one or more <rev>s  belong to the older half of the history,
>         you can say
>
>                 git bisect (good|old) [<rev>...]
>
> In contrast, you can mark only one <rev> as newer (or "already
> bad").  So pairing (bad|good) and (new|old) like you suggested
> breaks the correctness of the command line description.

Yeah, I agree.

> If (bad|new) and (good|old) bothers you because they may mislead the
> readers to think bad is an opposite of new (and good is an opposite
> of old), the only solution I can think of to that problem is to
> expand these two lines into four and list them like this:
>
>         git bisect bad [<rev>]
>         git bisect good [<rev>...]
>         git bisect new [<rev>]
>         git bisect old [<rev>...]

Maybe it would be more complete and a bit clearer if it was:

           git bisect (bad|new|<term-new>) [<rev>]
           git bisect (good|old|<term-old>) [<rev>...]

Re: Bug report: Documentation error in git-bisect man description

[Manuel Ullmann]

> On Fri, Jan 13, 2017 at 12:42 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> Manuel Ullmann <ullman.alias@posteo.de> writes:
>>>
>>> Hmmm, I tend to agree, modulo a minor fix.
>>>
>>> If the description were in a context inside a paragraph like this:
>>>
>>>       When you want to tell 'git bisect' that a <rev> belongs to
>>>       the newer half of the history, you say
>>>
>>>               git bisect (bad|new) [<rev>]
>>>
>>>       On the other hand, when you want to tell 'git bisect' that a
>>>       <rev> belongs to the older half of the history, you can say
>>>
>>>               git bisect (good|old) [<rev>]
>>>
>>> then the pairing we see in the current text makes quite a lot of
>>> sense.
>>
>> Actually, the above is _exactly_ what was intended.  I misread the
>> current documentation when I made the comment, and I think that the
>> current one _IS_ correct.  The latter half of the above is not about
>> a single rev.  You can paint multiple commits with the "older half"
>> color, i.e.
>>
>>         On the other hand, when you want to tell 'git bisect' that
>>         one or more <rev>s  belong to the older half of the history,
>>         you can say
>>
>>                 git bisect (good|old) [<rev>...]
>>
>> In contrast, you can mark only one <rev> as newer (or "already
>> bad").  So pairing (bad|good) and (new|old) like you suggested
>> breaks the correctness of the command line description.
>
> Yeah, I agree.
>
>> If (bad|new) and (good|old) bothers you because they may mislead the
>> readers to think bad is an opposite of new (and good is an opposite
>> of old), the only solution I can think of to that problem is to
>> expand these two lines into four and list them like this:
>>
>>         git bisect bad [<rev>]
>>         git bisect good [<rev>...]
>>         git bisect new [<rev>]
>>         git bisect old [<rev>...]
>
> Maybe it would be more complete and a bit clearer if it was:
>
>            git bisect (bad|new|<term-new>) [<rev>]
>            git bisect (good|old|<term-old>) [<rev>...]

That would clarify the intention quite a bit (at least for me).

Best regards,
Manuel