2.9. Using Bisect to Track Down Breakages

Oh no! Something is broken, and you don’t know why, or when it broke, and don’t know where to start looking. A common approach is to check out the repository at different revisions to figure out when the problem started happening, and to narrow it down by jumping around the range where the problem started happening, halving the range every time depending on whether the problem is there or not. Mercurial provides a command to make this easier: hg bisect.

You start the process, usually at the tip where the problem occurs, by telling Mercurial that it doesn’t work (after first resetting any previous bisect state):

hg bisect --reset
hg bisect --bad

Next, we need to either jump to, or define a revision we know the problem didn’t occur, some time in history. For example if we know already that it didn’t occur in revision 1300, we could do this:

hg bisect --good 1300

Otherwise, we could just jump to various revisions ourselves until we found one that worked, then just call hg bisect --good with no revision to tell hg that the current revision is ok. Either way, once you’ve told Mercurial the extent of the good/bad range, the working copy will be updated to a revision in between the known good & bad revisions for you to test again, and to call "hg bisect --good" or "hg bisect --bad" depending on the test results. Each time you do this, the working copy will update again to the next revision for testing, bisecting the range between good and bad. If you can script this, great! If not, you’ll be manually testing at each step.

Eventually you will find the case of a bad revision directly after a good revision, and hg will tell you. In this case, let’s assume we’ve just tested revision 1519 and found that it’s ok, but we’d previously tested 1520 and it wasn’t:

c:\myproject>hg bisect --good
The first bad revision is:
changeset:   1520:898fcb8708fc48
user:        Fred Bloggs <fred@bloggs.com>
date:        Wed Jan 11 07:25:04 2010 +0000
summary:     Some commit message