How to: Use git bisect to find bugs and regressions

Updated . Posted . Visible to the public. Repeats.

Git allows you to do a binary search across commits to hunt down the commit that introduced a bug.

Given you are currently on your branch's HEAD that is not working as expected, an example workflow could be:

git bisect start # Start bisecting
git bisect bad # Tag the revision you are currently on (HEAD) as bad. You could also pass a commit's SHA1 like below:
git bisect good abcdef12345678 # Give the SHA1 of any commit that was working as it should
# shorthand:
git bisect start <bad ref> <good ref>

Git will fetch a commit between the given good and bad commits.

You could then run a test (*) revealing the problem or inspect the issue manually. Keep in mind that you may need to migrate your database as Git is unaware of Rails and will not cast any magic.

If Git checked out a commit that is working:

git bisect good

If the current commit is bugged:

git bisect bad

Now, another commit will be checked out. See if the issue persists and call git bisect good or git bisect bad, resulting in another commit being fetched and so on.

Do this until Git reveals the commit which first contained the bug:

abc1234def5678 is the first bad commit
commit abc1234def5678
Author: John Doe <user@example.com>
Date: Thu Dec 23 13:37:00 2010 +0100
    make everything better

Once you are done bisecting you can go back with

git bisect reset

(*) Such a test would need to live outside the repository as you are constantly switching your working directory's state. Also, make sure to cover wording changes etc.

If you do, you can also have git find the bad commit automatically by using git bisect run.

Arne Hartherz
Last edit
Dominik Schöler
Keywords
git-bisect, guide, debug, debugging
License
Source code in this card is licensed under the MIT License.
Posted by Arne Hartherz to makandra dev (2011-01-11 12:28)