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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 12, 2017, 23:32 UTC
Message-ID: <xmqqd1frj1lt.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <87r347swz1.fsf@sonnengebleicht.fritz.box>

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

Show 16 quoted lines

> 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?