Re: [PATCH 01/16] bisect: write about `bisect next` in documentation

Stephan Beyer [off-list ref] writes:

I rephrase it as follows to not encourage checking out another branch
(or commit ;]) but to mention that it works to get back if someone
accidentally did it.

--8<--8<--8<--

Bisect next
~~~~~~~~~~~

In case you have marked a commit as bad but you do not know a good
commit, you do not have to crawl through the commit history yourself to
find a good commit. Simply issue the command:

------------
$ git bisect next
------------

This command is also handy when you accidentally checked out another
commit during a bisection. It computes the commit for the bisection
and checks it out again.

-->8-->8-->8--

Is that better?

Thanks, I think it is definitely better than the original patch.

I cannot say it is better than not having that extra paragraph,
though.  An immediate recovery after an accidental checkout can be
done with "git checkout -", and the only case "bisect next" is safe
and better is somebody accidentally checked multiple random commits
out without doing anything else (in which case you'd need to ask
reflog where the HEAD was in order to use "checkout" to go back).

But if they are doing more than just a single "checkout" immediately
followed by "oops that wasn't what I intended--now I want to go
back", they need more than "bisect next" or "checkout $somewhere"
anyway, so...

Hi,

On 02/27/2016 07:03 PM, Junio C Hamano wrote:

Stephan Beyer [off-list ref] writes:

quoted

This command is also handy when you accidentally checked out another
commit during a bisection. It computes the commit for the bisection
and checks it out again.

-->8-->8-->8--

Is that better?

Thanks, I think it is definitely better than the original patch.

I cannot say it is better than not having that extra paragraph,
though.

Okay, I will remove that extra paragraph.

However, it probably should be documented what "git bisect next" does
after you've specified bad and good commits.

For that, I'd like to have an extra informational paragraph.
What about: "In general, the command computes the next commit for the
bisection and checks it out."
This would be neutral, in the meaning that no use case is involved.

Another more "strict" choice could be to change the behavior such that
"git bisect next" dies when invoked after a good (and a bad) commit is
specified. In that case, there is no need to document the behavior ;-)
However, in that case the name of "git bisect next" would be wrong...

Cheers,
Stephan