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