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

> 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
>  +
>  ------------
>