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

On Fri, Jan 13, 2017 at 12:42 AM, Junio C Hamano [off-list ref] wrote:

quoted

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.

Yeah, I agree.

quoted

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