Re: [PATCH] git-bisect.txt: clarify that reset finishes bisect

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

Michael J Gruber wrote:

> "reset" can be easily misunderstood as resetting a bisect session to its
> start without finishing it. Clarify that it actually finishes the bisect
> session.

FWIW,
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Addressing Andreas's original concern about the discoverability of
'git bisect reset' would presumably require doing two more things:

 1. adding an example of the normal bisection workflow to the EXAMPLES
    section

 2. training users to look to the EXAMPLES section

That is, something like the below.  But I'm not happy with it, because
it just runs over the same material as the current Description
section.  Maybe the current tutorial material could be moved to
examples and replaced with something terser that fleshes out the
descriptions in "git bisect -h" output.  What do you think?

diff --git i/Documentation/git-bisect.txt w/Documentation/git-bisect.txt
index e4f46bc1..b89abd78 100644
--- i/Documentation/git-bisect.txt
+++ w/Documentation/git-bisect.txt
@@ -356,6 +356,54 @@ $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
 This shows that you can do without a run script if you write the test
 on a single line.
 
+* Bisect to find which patch caused a boot failure:
++
+Install a recent kernel:
++
+------------
+$ cd ~/src/linux
+$ git checkout origin/master
+$ make deb-pkg # or binrpm-pkg, or tar-pkg
+$ dpkg -i ../<name of package> # as root (or rpm -i, or tar -C / -xf)
+$ reboot # as root
+------------
++
+Hopefully it fails to boot, so tell git so and begin bisection:
++
+------------
+$ cd ~/src/linux
+$ git bisect start HEAD v3.2 # assuming 3.2 works fine
+-------------
++
+A candidate revision to test is automatically checked out.
+Test it:
++
+-------------
+$ make deb-pkg # or binrpm-pkg, or tar-pkg
+$ dpkg -i ../<name of package> # as root (or rpm -i, or tar -C / -xf)
+$ reboot # as root
+-------------
++
+Record the result:
++
+-------------
+$ cd ~/src/linux
+$ git bisect good # if it booted correctly
+$ git bisect bad # if it failed to boot
+$ git bisect skip # if some other bug made it hard to test
+-------------
++
+Repeat until bored or git prints the "first bad commit".  When
+done:
++
+-------------
+$ git bisect log >log # let others pick up where you left off
+$ git bisect reset HEAD # exit the bisecting state
+-------------
++
+At any step, you can run `git bisect visualize` to watch the
+regression range narrowing.
+
 * Locate a good region of the object graph in a damaged repository
 +
 ------------