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

[Stephan Beyer <s-beyer@gmx.net>]

Mention `bisect next` in the documentation of bisect.
`bisect next` is only useful in rare cases and the result
can also be accomplished using other utilities (like reflog).
However, it is available as a bisect command and should hence be
documented.

Also mention the use case when no good commit is known.
Some user message in git-bisect.sh is changed to reflect that
use case. It is also simplified: there is no need to mention
running `bisect start` explicitly, because it can be done
indirectly using `bisect bad`.

Signed-off-by: Stephan Beyer <s-beyer@gmx.net>
---

This patch considers the source code comment that says to be
"not sure we want 'next' at the UI level anymore", and replies with
"Yes, we want it!". Therefore, the "git bisect next" functionality
is explicitly motivated and documented.

The motivation of "having no good commit" is not made up. I am
working on a big project that is several years old and nearly
no test exists. So I add a test and things go wrong. However,
I know from using (an older version of) the project that a similar
case did work. So...I want to find the bad commit...
However, to make git bisect work, I always first had to find a good
commit, so I ended up doing the whole bisection process manually
(because I did not know that "git bisect next" existed).

I think that this change will help people who are also in these
situations.

 Documentation/git-bisect.txt | 25 +++++++++++++++++++++++++
 git-bisect.sh                | 15 ++++-----------
 2 files changed, 29 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index 7e79aae..8045e6d 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -27,6 +27,7 @@ on the subcommand:
  git bisect replay <logfile>
  git bisect log
  git bisect run <cmd>...
+ git bisect next
  git bisect help
 
 This command uses a binary search algorithm to find which commit in
@@ -66,6 +67,15 @@ checks it out, and outputs something similar to the following:
 Bisecting: 675 revisions left to test after this (roughly 10 steps)
 ------------------------------------------------
 
+Note that in cases you do not know a good commit,
+you can also start with:
+
+------------------------------------------------
+$ git bisect start
+$ git bisect bad                 # current version is bad
+$ git bisect next                # check out another commit
+------------------------------------------------
+
 You should now compile the checked-out version and test it. If that
 version works correctly, type
 
@@ -353,6 +363,21 @@ rewind the tree to the pristine state.  Finally the script should exit
 with the status of the real test to let the `git bisect run` command loop
 determine the eventual outcome of the bisect session.
 
+Bisect next
+~~~~~~~~~~~
+
+Sometimes it can be necessary to check out other branches during a bisect
+session. If you want to check out the next commit of the bisection again,
+simply issue the command:
+
+------------
+$ git bisect next
+------------
+
+Another typical use case of this command is when you have marked a commit
+as bad but you do not know a good commit. Instead of crawling through the
+history yourself, let this command check out a commit for you.
+
 OPTIONS
 -------
 --no-checkout::
diff --git a/git-bisect.sh b/git-bisect.sh
index 5d1cb00..5c93a27 100755
--- a/git-bisect.sh
+++ b/git-bisect.sh
@@ -334,16 +334,10 @@ bisect_next_check() {
 	*)
 		bad_syn=$(bisect_voc bad)
 		good_syn=$(bisect_voc good)
-		if test -s "$GIT_DIR/BISECT_START"
-		then
-
-			eval_gettextln "You need to give me at least one \$bad_syn and one \$good_syn revision.
-(You can use \"git bisect \$bad_syn\" and \"git bisect \$good_syn\" for that.)" >&2
-		else
-			eval_gettextln "You need to start by \"git bisect start\".
-You then need to give me at least one \$good_syn and one \$bad_syn revision.
-(You can use \"git bisect \$bad_syn\" and \"git bisect \$good_syn\" for that.)" >&2
-		fi
+		eval_gettextln "You need to give me at least one \$bad_syn revision.
+Use \"git bisect \$bad_syn\" for that. One \$good_syn revision is also helpful
+for bisecting (use \"git bisect \$good_syn\"). If you do not know one \$good_syn
+revision, you can use \"git bisect next\" to find one." >&2
 		exit 1 ;;
 	esac
 }
@@ -677,7 +671,6 @@ case "$#" in
 	skip)
 		bisect_skip "$@" ;;
 	next)
-		# Not sure we want "next" at the UI level anymore.
 		bisect_next "$@" ;;
 	visualize|view)
 		bisect_visualize "$@" ;;
-- 
2.7.1.354.gd492730.dirty