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

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 [off-list ref] writes:

quoted

Manuel Ullmann [off-list ref] 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>...]