How To Use Git Bisect

Historically, when trying to track down a bug in my code I spent a lot of time trying to determine exactly where the bug appears in the code. On all of my projects I use Git for version control. Knowing exactly which commit introduced the bug helps me track down the bug. Git bisect is a great tool for tracking down the commit where a bug was introduced.

A Git Bisect Example

I’ve created a Git repository at https://github.com/salcode/git-bisect-example that includes a bug introduced somewhere in its history. Feel free to clone this repository and try this out yourself.

When you first load the webpage in the repo, you’ll notice the text declares the page is blue but the page actually appears red. Clearly a bug has been introduced.

When can get a pretty list of the commits with

git log --color --graph --pretty=format:'%h -%d %s <%an>' --abbrev-commit

See my post for more information on how to improve Git log.

The output should look like

* 6f4cf6c - (HEAD -> master, origin/master) Add README.md <Sal Ferrarello>
* 54c9755 - Change heading to gray <Sal Ferrarello>
* 96884a3 - Change paragraph color to yellow <Sal Ferrarello>
* c034fa0 - Increase font size on body text <Sal Ferrarello>
* 407c8d8 - Change paragraph text alignment to right <Sal Ferrarello>
* e4e2bbc - Modify positioning to be absolute <Sal Ferrarello>
* 3c67b1d - Add div.repeats around paragraphs <Sal Ferrarello>
* 240a1bd - Change heading from h2 to h1 <Sal Ferrarello>
* f471090 - Add margin to the paragraphs <Sal Ferrarello>
* efbdcd2 - Add background color red behind the blue <Sal Ferrarello>
* d776c82 - Duplicate paragraph <Sal Ferrarello>
* 189abc6 - Add line breaks to paragraph <Sal Ferrarello>
* b27bb64 - Change the text color to white <Sal Ferrarello>
* c26c876 - Initial Commit <Sal Ferrarello>

Find a Commit That is Bad

Since the bug currently exists, we know the most recent commit 6f4cf6c is bad. A bad commit is any commit where the bug exists.

Find a Commit That is Good

Then we need to a find a commit that is good. Since there are relatively few commits in this repo, we’ll go back to the first commit (c26c876) and see if the problem exists there.

git checkout c26c876

As you can see, on commit c26c876 the background was blue, so this commit was good.

Now we know the bug was introduced somewhere from the good c26c876 and the bad 6f4cf6c.

Using Git Bisect

Now that we have both a good and a bad commit, we can use Git bisect.

To start the process type:

git bisect start
git bisect good c26c876
git bisect bad 6f4cf6c

Git will now automatically checkout one of the commits that occurred between the good and the bad commits.

We reload our HTML page and determine whether the problem exists here or not.

If the page is blue, we type

git bisect good

If the page is red, we type

git bisect bad

Git will then checkout a new commit and we repeat the process.

Eventually, git will output something like*:

abcxyz123 is the first bad commit

At this point, we are done with git bisect so we end the process with

git bisect reset

Now we know which commit is bad and we can review it with

git show abcxyz123

or through the web interface.

* Note: abcxyz123 is not a real commit on the https://github.com/salcode/git-bisect-example repository. If you can find the actual commit where the bug is introduced, mention it below in the comments.

Photo Credit

Pixabay

Sal Ferrarello (@salcode)

Sal is a PHP developer with a focus on the WordPress platform. He is a conference speaker with a background including Piano Player, Radio DJ, Magician/Juggler, Beach Photographer, and High School Math Teacher. Sal can be found professionally at WebDevStudios, where he works as a senior backend engineer.