diff options
| author | Vincent Pit <perl@profvince.com> | 2008-12-21 22:38:21 +0100 |
|---|---|---|
| committer | Vincent Pit <perl@profvince.com> | 2008-12-21 22:38:34 +0100 |
| commit | d82a90c1781ccf0f51c6d21d89bba736542ef4f8 (patch) | |
| tree | 01117919eff2e3d22b3055995d1301301ef38490 | |
| parent | f6c12373efa87e4286a97122c0ea72922ef8bcec (diff) | |
| download | perl-d82a90c1781ccf0f51c6d21d89bba736542ef4f8.tar.gz | |
A short introduction to git bisect.
| -rw-r--r-- | pod/perlrepository.pod | 47 |
1 files changed, 47 insertions, 0 deletions
diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod index 7b1b6191fb..34d464e0af 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<git> 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<perl> 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<HEAD> but wasn't in 5.10.0, C<git> 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<HEAD> and C<perl-5.10.0>. We can then run the bisecting process with: + + % git bisect run ~/run + +When the first bad commit is isolated, C<git bisect> will tell you so: + + ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit + commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 + Author: Dave Mitchell <davem@fdisolutions.com> + 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<git bisect log> and C<git bisect visualize>. C<git bisect reset> will get you out of bisect mode. + +Please note that the first C<good> state must be an ancestor of the first C<bad> state. If you want to search for the commit that I<solved> 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<good> and the upper as C<bad>. The "first bad commit" has then to be understood as the "first commit where the bug is solved". + +C<git help bisect> has much more information on how you can tweak your binary searches. |