=head2 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. You
-need an helper script that automates building C<perl> and running the
-testcase:
-
- % cat ~/run
- #!/bin/sh
- git clean -dxf
-
- # If you get './makedepend: 1: Syntax error: Unterminated quoted
- # string' when bisecting versions of perl older than 5.9.5 this hack
- # will work around the bug in makedepend.SH which was fixed in
- # version 96a8704c. Make sure to comment out `git checkout makedepend.SH'
- # below too.
- git show blead:makedepend.SH > makedepend.SH
-
- # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
- # if Encode is not needed for the test, you can speed up the bisect by
- # excluding it from the runs with -Dnoextensions=Encode
- sh Configure -des -Dusedevel -Doptimize="-g"
- test -f config.sh || exit 125
- # Correct makefile for newer GNU gcc
- perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile
- # if you just need miniperl, replace test_prep with miniperl
- make test_prep
- [ -x ./perl ] || exit 125
- ./perl -Ilib ~/testcase.pl
- ret=$?
- [ $ret -gt 127 ] && ret=127
- # git checkout makedepend.SH
- git clean -dxf
- exit $ret
-
-This script may return C<125> to indicate that the corresponding commit
-should be skipped. Otherwise, it returns the status of
-F<~/testcase.pl>.
+C<git> provides a built-in way to determine which commit should be blamed
+for introducing a given bug. C<git bisect> performs a binary search of
+history to locate the first failing commit. It is fast, powerful and
+flexible, but requires some setup and to automate the process an auxiliary
+shell script is needed.
+
+The core provides a wrapper program, F<Porting/bisect.pl>, which attempts to
+simplify as much as possible, making bisecting as simple as running a Perl
+one-liner. For example, if you want to know when this became an error:
+
+ perl -e 'my $a := 2'
+
+you simply run this:
+
+ .../Porting/bisect.pl -e 'my $a := 2;'
+
+Using C<bisect.pl>, with one command (and no other files) it's easy to find
+out
+
+=over 4
+
+=item *
+
+Which commit caused this example code to break?
+
+=item *
+
+Which commit caused this example code to start working?
+
+=item *
+
+Which commit added the first file to match this regex?
+
+=item *
+
+Which commit removed the last file to match this regex?
+
+=back
+
+usually without needing to know which versions of perl to use as start and
+end revisions, as F<bisect.pl> automatically searches to find the earliest
+stable version for which the test case passes. Run
+C<Porting/bisect.pl --help> for the full documentation, including how to
+set the C<Configure> and build time options.
+
+If you require more flexibility than F<Porting/bisect.pl> has to offer, you'll
+need to run C<git bisect> yourself. It's most useful to use C<git bisect run>
+to automate the building and testing of perl revisions. For this you'll need
+a shell script for C<git> to call to test a particular revision. An example
+script is F<Porting/bisect-example.sh>, which you should copy B<outside> of
+the repository, as the bisect process will reset the state to a clean checkout
+as it runs. The instructions below assume that you copied it as F<~/run> and
+then edited it as appropriate.
You first enter in bisect mode with:
commit. You should perform your work on a L<topic branch|/Topic
branches and rewriting history>, which you should regularly rebase
against blead to ensure that your code is not broken by blead moving.
-When you have finished your work and performed a final rebase and test,
-you can merge it into master like this (assuming your work was on the
+When you have finished your work, please perform a final rebase and
+test. Linear history is something that gets lost with every
+commit on blead, but a final rebase makes the history linear
+again, making it easier for future maintainers to see what has
+happened. Rebase as follows (assuming your work was on the
branch C<< committer/somework >>):
+ $ git checkout committer/somework
+ $ git rebase blead
+
+Then you can merge it into master like this:
+
$ git checkout blead
$ git merge --no-ff --no-commit committer/somework
$ git commit -a
https://perl5.git.perl.org / perl5.git / blobdiff