From: Vincent Pit Date: Sun, 21 Dec 2008 21:38:21 +0000 (+0100) Subject: A short introduction to git bisect. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=d82a90c1781ccf0f51c6d21d89bba736542ef4f8;p=p5sagit%2Fp5-mst-13.2.git A short introduction to git bisect. --- diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod index 7b1b619..34d464e 100644 --- a/pod/perlrepository.pod +++ b/pod/perlrepository.pod @@ -365,3 +365,50 @@ However, be aware this will delete ALL untracked content. You can use to remove all ignored untracked files, such as build and test byproduct, but leave any manually created files alone. +=head1 BISECTING + +C provides a built-in way to determine, with a binary search in the history, which commit should be blamed for introducing a given bug. + +Suppose that we have a script F<~/testcase.pl> that exits with C<0> when some behaviour is correct, and with C<1> when it's faulty. We need an helper script that automates building C and running the testcase: + + % cat ~/run + #!/bin/sh + git clean -dxf + # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line + sh Configure -des -Dusedevel -Doptimize="-g" || exit 125 + make || exit 125 + ./perl -Ilib ~/testcase.pl + +This script may return C<125> to indicate that the corresponding commit should be skipped. Otherwise, it returns the status of F<~/testcase.pl>. + +We first enter in bisect mode with: + + % git bisect start + +For example, if the bug is present on C but wasn't in 5.10.0, C will learn about this when you enter: + + % git bisect bad + % git bisect good perl-5.10.0 + Bisecting: 853 revisions left to test after this + +This results in checking out the median commit between C and C. We can then run the bisecting process with: + + % git bisect run ~/run + +When the first bad commit is isolated, C will tell you so: + + ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit + commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 + Author: Dave Mitchell + Date: Sat Feb 9 14:56:23 2008 +0000 + + [perl #49472] Attributes + Unkown Error + ... + + bisect run success + +You can peek into the bisecting process with C and C. C will get you out of bisect mode. + +Please note that the first C state must be an ancestor of the first C state. If you want to search for the commit that I some bug, you have to negate your test case (i.e. exit with C<1> if OK and C<0> if not) and still mark the lower bound as C and the upper as C. The "first bad commit" has then to be understood as the "first commit where the bug is solved". + +C has much more information on how you can tweak your binary searches.