From: Junio C Hamano Date: Wed, 23 Mar 2011 04:38:15 +0000 (-0700) Subject: Merge branch 'mg/doc-bisect-tweak-worktree' X-Git-Tag: v1.7.5-rc0~39 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/b350f7797c43ae488fb6d4d0faaa08e931445b2d?hp=-c 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 --- b350f7797c43ae488fb6d4d0faaa08e931445b2d diff --combined Documentation/git-bisect.txt index 4b4b096ce5,989e2238d6..7b7bafba0c --- a/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 - -Documentation -------------- -Documentation by Junio C Hamano and the git-list . - SEE ALSO -------- link:git-bisect-lk2009.html[Fighting regressions with git bisect],