Re: [PATCH v9 5/5] bisect: allow any terms set by user

[Junio C Hamano <gitster@pobox.com>]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> The second sentence may want to be something like
>>
>> 	If you mistyped one of the terms, you can do another "git
>> 	bisect terms <term-new> <term-old>" to correct them, but
>> 	that is possible only before you start the bisection.
>
> Applied, thanks.

I didn't say it out loud while writing the above, but this (and we
have other places that use the same phrase in the doc) mentions that
you have some point in time where you "start" the bisection, without
having a clear definition of where that bisection starts, and that
bothers me.  "You can do X until you do Y", when it is not clear
what Y exactly happens, is not very helpful.

We who know how bisection works internally know that the point of no
return is when we commit to the two terms and write one of the good
or bad bisect refs.  At that point, technically we haven't done a
bisection yet ("git bisect good maint" would bisect_autostart, but
without the other end, does not have a graph to bisect yet to find a
midpoint).

And worse yet, majority of users may read "git bisect start" is
where "you start bisection", but "bisect start" (either called
directly, or via bisect_autostart by the first "git bisect good")
is where you set up the machinery, so doing "bisect terms" before
doing "bisect start" does not make much sense.



> I currently have this in addition to v9 in my branch. I'll resend later
> (https://github.com/moy/git/tree/bisect-terms is up to date).
>
> diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
> index e783f87..7609cd6 100644
> --- a/Documentation/git-bisect.txt
> +++ b/Documentation/git-bisect.txt
> @@ -143,19 +143,19 @@ set your own terms.
>  git bisect terms <term-new> <term-old>
>  ------------------------------------------------
>  
> -This command has to be used before a bisection has started. <term-old>
> -must be associated with the latest revisions and <term-new> with the
> -ancestors of <term-old>. For example, if something was buggy in the
> +This command has to be used before a bisection has started. <term-new>
> +must be associated with the latest revisions and <term-old> with some
> +ancestors of <term-new>. For example, if something was buggy in the
>  old part of the history, you know somewhere the bug was fixed, and you
>  want to find the exact commit that fixed it, you may want to say `git
> -bisect terms fixed broken`; this way, you would mark a commit that
> +bisect terms broken fixed`; this way, you would mark a commit that

The example talks about a bug we used to have that was corrected, so
"broken" is old and "fixed" is new.  The earlier parts of this hunk
are correct but the last line should not be changed, no?

There unfortunately are two reasons why we cannot flip the order to
"git bisect terms old new":

 * "git bisect start $bad $good" established the
   convention to list bad before good (and 'B'ad comes before
   'G'ood, so does 'N'ew before 'O'ld).

 * "git bisect start $good $bad", even if we could use a time
   machine, would not be a good syntax, as you give zero or more
   good ones and one and only one bad one.