diff options
Diffstat (limited to 'Documentation/git-bisect.txt')
| -rw-r--r-- | Documentation/git-bisect.txt | 399 |
1 files changed, 333 insertions, 66 deletions
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 16ec7269b2..e97f2de21b 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -3,134 +3,401 @@ git-bisect(1) NAME ---- -git-bisect - Find the change that introduced a bug by binary search +git-bisect - Use binary search to find the commit that introduced a bug SYNOPSIS -------- -'git bisect' <subcommand> <options> +[verse] +'git bisect' <subcommand> <options> DESCRIPTION ----------- -The command takes various subcommands, and different options -depending on the subcommand: - - git bisect start [<paths>...] - git bisect bad <rev> - git bisect good <rev> - git bisect reset [<branch>] +The command takes various subcommands, and different options depending +on the subcommand: + + git bisect start [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] + git bisect bad [<rev>] + git bisect good [<rev>...] + git bisect skip [(<rev>|<range>)...] + git bisect reset [<commit>] git bisect visualize git bisect replay <logfile> git bisect log + git bisect run <cmd>... + git bisect help + +This command uses a binary search algorithm to find which commit in +your project's history introduced a bug. You use it by first telling +it a "bad" commit that is known to contain the bug, and a "good" +commit that is known to be before the bug was introduced. Then `git +bisect` picks a commit between those two endpoints and asks you +whether the selected commit is "good" or "bad". It continues narrowing +down the range until it finds the exact commit that introduced the +change. -This command uses 'git-rev-list --bisect' option to help drive -the binary search process to find which change introduced a bug, -given an old "good" commit object name and a later "bad" commit -object name. +Basic bisect commands: start, bad, good +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The way you use it is: +As an example, suppose you are trying to find the commit that broke a +feature that was known to work in version `v2.6.13-rc2` of your +project. You start a bisect session as follows: ------------------------------------------------ $ git bisect start -$ git bisect bad # Current version is bad -$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version - # tested that was good +$ git bisect bad # Current version is bad +$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 is known to be good +------------------------------------------------ + +Once you have specified at least one bad and one good commit, `git +bisect` selects a commit in the middle of that range of history, +checks it out, and outputs something similar to the following: + +------------------------------------------------ +Bisecting: 675 revisions left to test after this (roughly 10 steps) ------------------------------------------------ -When you give at least one bad and one good versions, it will -bisect the revision tree and say something like: +You should now compile the checked-out version and test it. If that +version works correctly, type ------------------------------------------------ -Bisecting: 675 revisions left to test after this +$ git bisect good ------------------------------------------------ -and check out the state in the middle. Now, compile that kernel, and boot -it. Now, let's say that this booted kernel works fine, then just do +If that version is broken, type ------------------------------------------------ -$ git bisect good # this one is good +$ git bisect bad ------------------------------------------------ -which will now say +Then `git bisect` will respond with something like ------------------------------------------------ -Bisecting: 337 revisions left to test after this +Bisecting: 337 revisions left to test after this (roughly 9 steps) ------------------------------------------------ -and you continue along, compiling that one, testing it, and depending on -whether it is good or bad, you say "git bisect good" or "git bisect bad", -and ask for the next bisection. +Keep repeating the process: compile the tree, test it, and depending +on whether it is good or bad run `git bisect good` or `git bisect bad` +to ask for the next commit that needs testing. + +Eventually there will be no more revisions left to inspect, and the +command will print out a description of the first bad commit. The +reference `refs/bisect/bad` will be left pointing at that commit. + -Until you have no more left, and you'll have been left with the first bad -kernel rev in "refs/bisect/bad". +Bisect reset +~~~~~~~~~~~~ -Oh, and then after you want to reset to the original head, do a +After a bisect session, to clean up the bisection state and return to +the original HEAD, issue the following command: ------------------------------------------------ $ git bisect reset ------------------------------------------------ -to get back to the master branch, instead of being in one of the bisection -branches ("git bisect start" will do that for you too, actually: it will -reset the bisection state, and before it does that it checks that you're -not using some old bisection branch). +By default, this will return your tree to the commit that was checked +out before `git bisect start`. (A new `git bisect start` will also do +that, as it cleans up the old bisection state.) -During the bisection process, you can say +With an optional argument, you can return to a different commit +instead: + +------------------------------------------------ +$ git bisect reset <commit> +------------------------------------------------ + +For example, `git bisect reset bisect/bad` will check out the first +bad revision, while `git bisect reset HEAD` will leave you on the +current bisection commit and avoid switching commits at all. + + +Bisect visualize +~~~~~~~~~~~~~~~~ + +To see the currently remaining suspects in 'gitk', issue the following +command during the bisection process: ------------ $ git bisect visualize ------------ -to see the currently remaining suspects in `gitk`. +`view` may also be used as a synonym for `visualize`. -The good/bad input is logged, and `git bisect -log` shows what you have done so far. You can truncate its -output somewhere and save it in a file, and run +If the 'DISPLAY' environment variable is not set, 'git log' is used +instead. You can also give command-line options such as `-p` and +`--stat`. ------------ +$ git bisect view --stat +------------ + +Bisect log and bisect replay +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After having marked revisions as good or bad, issue the following +command to show what has been done so far: + +------------ +$ git bisect log +------------ + +If you discover that you made a mistake in specifying the status of a +revision, you can save the output of this command to a file, edit it to +remove the incorrect entries, and then issue the following commands to +return to a corrected state: + +------------ +$ git bisect reset $ git bisect replay that-file ------------ -if you find later you made a mistake telling good/bad about a -revision. +Avoiding testing a commit +~~~~~~~~~~~~~~~~~~~~~~~~~ + +If, in the middle of a bisect session, you know that the suggested +revision is not a good one to test (e.g. it fails to build and you +know that the failure does not have anything to do with the bug you +are chasing), you can manually select a nearby commit and test that +one instead. -If in a middle of bisect session, you know what the bisect -suggested to try next is not a good one to test (e.g. the change -the commit introduces is known not to work in your environment -and you know it does not have anything to do with the bug you -are chasing), you may want to find a near-by commit and try that -instead. It goes something like this: +For example: ------------ -$ git bisect good/bad # previous round was good/bad. -Bisecting: 337 revisions left to test after this +$ git bisect good/bad # previous round was good or bad. +Bisecting: 337 revisions left to test after this (roughly 9 steps) $ git bisect visualize # oops, that is uninteresting. -$ git reset --hard HEAD~3 # try 3 revs before what +$ git reset --hard HEAD~3 # try 3 revisions before what # was suggested ------------ -Then compile and test the one you chose to try. After that, -tell bisect what the result was as usual. +Then compile and test the chosen revision, and afterwards mark +the revision as good or bad in the usual manner. + +Bisect skip +~~~~~~~~~~~~ + +Instead of choosing a nearby commit by yourself, you can ask Git to do +it for you by issuing the command: + +------------ +$ git bisect skip # Current version cannot be tested +------------ + +However, if you skip a commit adjacent to the one you are looking for, +Git will be unable to tell exactly which of those commits was the +first bad one. + +You can also skip a range of commits, instead of just one commit, +using range notation. For example: + +------------ +$ git bisect skip v2.5..v2.6 +------------ + +This tells the bisect process that no commit after `v2.5`, up to and +including `v2.6`, should be tested. -You can further cut down the number of trials if you know what -part of the tree is involved in the problem you are tracking -down, by giving paths parameters when you say `bisect start`, -like this: +Note that if you also want to skip the first commit of the range you +would issue the command: ------------ -$ git bisect start arch/i386 include/asm-i386 +$ git bisect skip v2.5 v2.5..v2.6 ------------ +This tells the bisect process that the commits between `v2.5` and +`v2.6` (inclusive) should be skipped. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> -Documentation -------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +Cutting down bisection by giving more parameters to bisect start +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can further cut down the number of trials, if you know what part of +the tree is involved in the problem you are tracking down, by specifying +path parameters when issuing the `bisect start` command: + +------------ +$ git bisect start -- arch/i386 include/asm-i386 +------------ + +If you know beforehand more than one good commit, you can narrow the +bisect space down by specifying all of the good commits immediately after +the bad commit when issuing the `bisect start` command: + +------------ +$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 -- + # v2.6.20-rc6 is bad + # v2.6.20-rc4 and v2.6.20-rc1 are good +------------ + +Bisect run +~~~~~~~~~~ + +If you have a script that can tell if the current source code is good +or bad, you can bisect by issuing the command: + +------------ +$ git bisect run my_script arguments +------------ + +Note that the script (`my_script` in the above example) should exit +with code 0 if the current source code is good/old, and exit with a +code between 1 and 127 (inclusive), except 125, if the current source +code is bad/new. + +Any other exit code will abort the bisect process. It should be noted +that a program that terminates via `exit(-1)` leaves $? = 255, (see the +exit(3) manual page), as the value is chopped with `& 0377`. + +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). 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 +header file, or "revision that does not have this commit needs this +patch applied to work around another problem this bisection is not +interested in") applied to the revision being tested. + +To cope with such a situation, after the inner 'git bisect' finds the +next revision to test, the script can apply the patch +before compiling, run the real test, and afterwards decide if the +revision (possibly with the needed patch) passed the test and then +rewind the tree to the pristine state. Finally the script should exit +with the status of the real test to let the `git bisect run` command loop +determine the eventual outcome of the bisect session. + +OPTIONS +------- +--no-checkout:: ++ +Do not checkout the new working tree at each iteration of the bisection +process. Instead just update a special reference named 'BISECT_HEAD' to make +it point to the commit that should be tested. ++ +This option may be useful when the test you would perform in each step +does not require a checked out tree. ++ +If the repository is bare, `--no-checkout` is assumed. + +EXAMPLES +-------- + +* Automatically bisect a broken build between v1.2 and HEAD: ++ +------------ +$ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good +$ git bisect run make # "make" builds the app +$ git bisect reset # quit the bisect session +------------ + +* Automatically bisect a test failure between origin and HEAD: ++ +------------ +$ git bisect start HEAD origin -- # HEAD is bad, origin is good +$ git bisect run make test # "make test" builds and tests +$ git bisect reset # quit the bisect session +------------ + +* Automatically bisect a broken test case: ++ +------------ +$ cat ~/test.sh +#!/bin/sh +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 +$ git bisect reset # quit the bisect session +------------ ++ +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 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 with temporary modifications (hot-fix): ++ +------------ +$ cat ~/test.sh +#!/bin/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 +------------ ++ +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 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" +$ git bisect reset # quit the bisect session +------------ ++ +This shows that you can do without a run script if you write the test +on a single line. + +* Locate a good region of the object graph in a damaged repository ++ +------------ +$ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout +$ git bisect run sh -c ' + GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) && + git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ && + git pack-objects --stdout >/dev/null <tmp.$$ + rc=$? + rm -f tmp.$$ + test $rc = 0' + +$ git bisect reset # quit the bisect session +------------ ++ +In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that +has at least one parent whose reachable graph is fully traversable in the sense +required by 'git pack objects'. + +Getting help +~~~~~~~~~~~~ + +Use `git bisect` to get a short usage description, and `git bisect +help` or `git bisect -h` to get a long usage description. + +SEE ALSO +-------- +link:git-bisect-lk2009.html[Fighting regressions with git bisect], +linkgit:git-blame[1]. GIT --- -Part of the gitlink:git[7] suite - +Part of the linkgit:git[1] suite |