What is Mercurial bisect good for?

Question

I've been reading about hg bisect and its interesting to be able to know which revision introduced a bug, but I'd like to know what people use this information for. The only thing I can think of is trying to narrow down which dates might need a data fix if it's a bug that results in some form of invalid data.

update: I think I completely misunderstood the purpose before I posted this. I was thinking that I would do the debugging and find which line(s) introduced the bug and then use bisect. It seems bisect is a way for me to not have to spend time guessing where the bug might be and placing breakpoints or logging. Instead I should write a small test that fails now, passes in a past revision and have bisect tell me where the problem originates.

Answer 1

The bisect command helps you find the changeset that introduced a bug. It often happens that you realize that something is broken and that it has been broken for a while. With hg bisect, you can figure out exactly when it became broken. When you know that, it is often much easier to fix the problem.

It works like this. You start by resetting the bisect state and marking the current revision as bad since it contains the bug:

$ hg bisect --reset
$ hg bisect --bad

You then jump back in history to a point where you hope the bug is not present:

$ hg update -r -100
89 files updated, 0 files merged, 30 files removed, 0 files unresolved

You have to test your software at this revision and if the bug is not present, then you can mark it as good:

$ hg bisect --good
Testing changeset 11964:79bd860b8eb7 (81 changesets remaining, ~6 tests)
36 files updated, 0 files merged, 22 files removed, 0 files unresolved

When you marked it as good, Mercurial updated your working copy to a place roughly in the middle between the good and bad changesets. You now have to test this changeset and mark it good/bad.

$ hg bisect --good
Testing changeset 11985:81edef14922e (41 changesets remaining, ~5 tests)
23 files updated, 0 files merged, 26 files removed, 0 files unresolved

I continue like this until Mercurial has narrowed the search down to a single changeset:

$ hg bisect --bad
Testing changeset 11975:21884b433c51 (20 changesets remaining, ~4 tests)
18 files updated, 0 files merged, 8 files removed, 0 files unresolved
$ hg bisect --good
Testing changeset 11980:c443e95d295b (10 changesets remaining, ~3 tests)
5 files updated, 0 files merged, 10 files removed, 0 files unresolved
$ hg bisect --good
Testing changeset 11982:56d9b73487ff (5 changesets remaining, ~2 tests)
2 files updated, 0 files merged, 4 files removed, 0 files unresolved
$ hg bisect --bad
Testing changeset 11981:518b90d66fad (2 changesets remaining, ~1 tests)
2 files updated, 0 files merged, 1 files removed, 0 files unresolved
$ hg bisect --bad
The first bad revision is:
changeset:   11981:518b90d66fad
user:        Pradeepkumar Gayam <[email protected]>
date:        Wed Aug 18 05:55:56 2010 +0530
summary:     tests: unify test-merge8

You still have to do the debugging yourself, but using hg bisect saves you from keeping track of which changesets you have already tested and which you still need to test. You could use a bunch of post-it notes for this, but it's much nicer to let Mercurial do it. This is especially true when the changeset graph is is non-linear because of merges.

So all in all, hg bisect helps you do a search for a faulty changeset in logarithmic time, without you having to keep track of where you are in the search.

Answer 2

To track down the changeset that introduced a bug. I think it's obvious that this is very useful. If your software suddenly fails and you don't know which change caused the bug bisect makes it easy to track down that change. I don't get at all what you're saying about dates.

Answer 3

It might not be obvious from the symptom of a bug exactly what its cause is - e.g. you might get a very generic error or an unclear error message. Using hg bisect lets you find the cause.