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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 12, 2017, 23:42 UTC
Message-ID: <xmqq8tqfj15z.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <xmqqd1frj1lt.fsf@gitster.mtv.corp.google.com>

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

Show 18 quoted lines

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