Merge branch 'mg/doc-bisect-tweak-worktree'

* mg/doc-bisect-tweak-worktree:
  git-bisect.txt: example for bisecting with hot-fix
  git-bisect.txt: streamline run presentation

diff --combined Documentation/git-bisect.txt
index 4b4b096ce5390d4343c73fe187d686e7072d3549,989e2238d653f2141a8cca061412f043ef13bcae..7b7bafba0c514755f9eec423b5aed19db640c091
--- 1/Documentation/git-bisect.txt
--- 2/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@@ -241,12 -241,7 +241,12 @@@ exit(3) manual page), as the value is c
  
  The special exit code 125 should be used when the current source code
  cannot be tested. If the script exits with this code, the current
 -revision will be skipped (see `git bisect skip` above).
 +revision will be skipped (see `git bisect skip` above). 125 was chosen
 +as the highest sensible value to use for this purpose, because 126 and 127
 +are used by POSIX shells to signal specific error status (127 is for
 +command not found, 126 is for command found but not executable---these
 +details do not matter, as they are normal errors in the script, as far as
 +"bisect run" is concerned).
  
  You may often find that during a bisect session you want to have
  temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a
@@@ -279,54 -274,77 +279,69 @@@ $ git bisect start HEAD origin --    # 
  $ git bisect run make test           # "make test" builds and tests
  ------------
  
- * Automatically bisect a broken test suite:
+ * Automatically bisect a broken test case:
  +
  ------------
  $ cat ~/test.sh
  #!/bin/sh
- make || exit 125                   # this skips broken builds
- make test                          # "make test" runs the test suite
- $ git bisect start v1.3 v1.1 --    # v1.3 is bad, v1.1 is good
+ make || exit 125                     # this skips broken builds
+ ~/check_test_case.sh                 # does the test case pass?
+ $ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
  $ git bisect run ~/test.sh
  ------------
  +
  Here we use a "test.sh" custom script. In this script, if "make"
  fails, we skip the current commit.
+ "check_test_case.sh" should "exit 0" if the test case passes,
+ and "exit 1" otherwise.
  +
- It is safer to use a custom script outside the repository to prevent
- interactions between the bisect, make and test processes and the
- script.
- +
- "make test" should "exit 0", if the test suite passes, and
- "exit 1" otherwise.
+ It is safer if both "test.sh" and "check_test_case.sh" are
+ outside the repository to prevent interactions between the bisect,
+ make and test processes and the scripts.
  
- * Automatically bisect a broken test case:
+ * Automatically bisect with temporary modifications (hot-fix):
  +
  ------------
  $ cat ~/test.sh
  #!/bin/sh
- make || exit 125                     # this skips broken builds
- ~/check_test_case.sh                 # does the test case passes ?
- $ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
- $ git bisect run ~/test.sh
+ 
+ # tweak the working tree by merging the hot-fix branch
+ # and then attempt a build
+ if    git merge --no-commit hot-fix &&
+       make
+ then
+       # run project specific test and report its status
+       ~/check_test_case.sh
+       status=$?
+ else
+       # tell the caller this is untestable
+       status=125
+ fi
+ 
+ # undo the tweak to allow clean flipping to the next commit
+ git reset --hard
+ 
+ # return control
+ exit $status
  ------------
  +
- Here "check_test_case.sh" should "exit 0" if the test case passes,
- and "exit 1" otherwise.
- +
- It is safer if both "test.sh" and "check_test_case.sh" scripts are
- outside the repository to prevent interactions between the bisect,
- make and test processes and the scripts.
+ This applies modifications from a hot-fix branch before each test run,
+ e.g. in case your build or test environment changed so that older
+ revisions may need a fix which newer ones have already. (Make sure the
+ hot-fix branch is based off a commit which is contained in all revisions
+ which you are bisecting, so that the merge does not pull in too much, or
+ use `git cherry-pick` instead of `git merge`.)
  
- * Automatically bisect a broken test suite:
+ * Automatically bisect a broken test case:
  +
  ------------
  $ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
  $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
  ------------
  +
- Does the same as the previous example, but on a single line.
+ This shows that you can do without a run script if you write the test
+ on a single line.
  
 -Author
 -------
 -Written by Linus Torvalds <torvalds@osdl.org>
 -
 -Documentation
 --------------
 -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 -
  SEE ALSO
  --------
  link:git-bisect-lk2009.html[Fighting regressions with git bisect],