• Choose a category
• All
• Classic-Fiction

The sizes of the components of your project that you ship exploded recently, and you suspect that something changed in the way you build your project.

From these examples, it should be clear that the hg bisect command is not useful only for finding the sources of bugs. You can use it to find any “emergent property” of a repository (anything that you can’t find from a simple text search of the files in the tree) for which you can write a binary test.

We’ll introduce a little bit of terminology here, just to make it clear which parts of the search process are your responsibility, and which are Mercurial’s. A test is something that you run when hg bisect chooses a changeset. A probe is what hg bisect runs to tell whether a revision is good. Finally, we’ll use the word “bisect,” as both a noun and a verb, to stand in for the phrase “search using the hg bisect command.”

One simple way to automate the searching process would be simply to probe every changeset. However, this scales poorly. If it took ten minutes to test a single changeset and you had 10,000 changesets in your repository, the exhaustive approach would take on average 35 days to find the changeset that introduced a bug. Even if you knew that the bug was introduced by one of the last 500 changesets and limited your search to those, you’d still be looking at over 40 hours to find the changeset that introduced your bug.

What the hg bisect command does is use its knowledge of the “shape” of your project’s revision history to perform a search in time proportional to the logarithm of the number of changesets to check (the kind of search it performs is called a dichotomic search). With this approach, searching through 10,000 changesets will take less than three hours, even at ten minutes per test (the search will require about 14 tests). Limit your search to the last hundred changesets, and it will take only about an hour (roughly seven tests).

The hg bisect command is aware of the “branchy” nature of a Mercurial project’s revision history, so it has no problems dealing with branches, merges, or multiple heads in a repository. It can prune entire branches of history with a single probe, which is how it operates so efficiently.

Using the hg bisect Command

Here’s an example of hg bisect in action.

* * *

Note

In versions 0.9.5 and earlier of Mercurial, hg bisect was not a core command: it was distributed with Mercurial as an extension. This section describes the built-in command, not the old extension.

* * *

Let’s create a repository, so that we can try out the hg bisect command in isolation.

$ hg init mybug

$ cd mybug

We’ll simulate a project that has a bug in it in a simple-minded way: create trivial changes in a loop, and nominate one specific change that will have the “bug.” This loop creates 35 changesets, each adding a single file to the repository. We’ll represent our “bug” with a file that contains the text “i have a gub”.

$ buggy_change=22

$ for (( i = 0; i < 35; i++ )); do

> if [[ $i = $buggy_change ]]; then

> echo 'i have a gub' > myfile$i

> hg commit -q -A -m 'buggy changeset'

> else

> echo 'nothing to see here, move along' > myfile$i

> hg commit -q -A -m 'normal changeset'

> fi

> done

The next thing that we’d like to do is figure out how to use the hg bisect command. We can use Mercurial’s normal built-in help mechanism for this.

$ hg help bisect

hg bisect [-gbsr] [-c CMD] [REV]

subdivision search of changesets

This command helps to find changesets which introduce problems.

To use, mark the earliest changeset you know exhibits the problem

as bad, then mark the latest changeset which is free from the

problem as good. Bisect will update your working directory to a

revision for testing (unless the --noupdate option is specified).

Once you have performed tests, mark the working directory as bad

or good and bisect will either update to another candidate changeset

or announce that it has found the bad revision.

As a shortcut, you can also use the revision