We’ve all been there before.  We pull a fresh copy of our project and now it’s not working.  If you’re on a team project, trying to pinpoint where the issue started can seem like a nightmare.  Well, for the first time since I started working on our game project (my internship), I was unable to run the game, and there were roughly a month’s worth of commits between the fresh pull and the last time that the game worked properly on my computer.

My first instinct was to perform an expertly executed table flip and walk out of the room.  But instead, great tips from my friend helped me through a pretty awesome bit of functionality of git, git-bisect.

So what is this git-bisect thing you speak of?

Well, it’s a way to step through your commits while git determines which commit was the culprit.  Groovy, huh?  Git bisect will automatically figure out which commits need to be tested in order to pinpoint which commit is causing your program to fail.  So, how does this work?

First, you have to let git know that you are about to begin bisecting the code.

[code language=”python”]
$ git bisect start
[/code]

This toggles the “bisect mode” and starts the bisecting process.  Next, you have to let git know which commit is bad:

[code language=”python”]
$ git bisect bad
[/code]

Usually this is on the current commit. After this, you have to find and checkout a commit roughly near the last working commit. This does not have to be the exact last working commit, git will help determine this info, you just need to find a previously working commit to flag.  In my situation, it had been awhile, so I just moved the HEAD back 50 commits.

[code language=”python”]
$ git checkout HEAD~50
[/code]

Then I tested the game and determined that it worked.  So now I have a rough point, again in my case, it had been quite some time, you may either know the commit or only have to go back a few commits to test.  Either way, now it’s time to flag the working commit so that git has a range to bisect.  For the first working commit, you have to tell git the actual commit,  git rev-parse HEAD will give you the current commit, and then you can pass it through to git using the “git bisect good” command.

[code language=”python”]
$ git rev-parse HEAD
$ git bisect good [commit]
Bisecting: 14 revisions left to test after this (roughly 4 steps)
[/code]

Note that if your shell supports it, you can combine the above commands to one: git bisect good $(git rev-parse HEAD)

Now git tells us that it has determined which commits needs to be tested, after each bisect, you have to recompile and test your code to see if the problem still exists.  In my case, the code was still not working so I flagged that commit as being bad.

[code language=”python”]
$ git bisect bad
[/code]

Git will continue going through the steps, each time you run your code to see if the problem exists, each time entering the command “git bisect good” if it is working, or “git bisect bad” if it’s not.  Finally, you will run out of steps and git will spit out information about the culprit commit that is causing you so much heartache.

After you’ve noted the offending commit, you have to let git know that you are done bisecting and it will reset you back to the commit prior to beginning the bisecting process:

[code language=”python”]
$ git bisect reset
[/code]

I found this process pretty awesome.  In my situation, when the game did not run, I expected that there was an issue in the very last commit and that everyone else shared the same issue.  But after verifying that we were all on the freshest copy of the game and no one else was able to duplicate my issue, I was left trying to determine a system-specific bug, and only I could handle that.  This git functionality was very useful in helping me determine the origin of my issue.

 

Mira is a Senior Full Stack, specializing in Web Applications developed in the healthcare industry.