Advanced Git Bisect Techniques

the bug you are chasing), you can manually select a nearby commit and test that one instead. For example: ------------ $ 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 revisions before what # was suggested ------------ 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. Note that if you also want to skip the first commit of the range you would issue the command: ------------ $ 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. 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 pathspec 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

Git bisect provides several advanced features to aid in the debugging process, including the ability to skip commits or ranges of commits, specify path parameters to narrow down the search, and use scripts to automate the testing process. The 'bisect start' command can be used with multiple good commits to further reduce the number of trials, and the 'bisect run' command can be used to execute a script that determines whether the current source code is good or bad.