git bisect start
git bisect bad <bad-commit-sha>
git bisect good <safe-commit-sha>
git bisect run <command-proving-existence-of-bug>
...
git bisect reset

Introduction

git bisect can be used to find the commit that introduced a bug. It’s a multi-step process, and, like a lot of Git’s user interface, can appear intimidating. However, I think it’s actually pretty user-friendly, and hope that by the end of this walk-through that you’ll feel comfortable enough to add it to your debugging arsenal.

When to reach for git bisect

If you’ve got a bug in your codebase, but you’re not sure when it was introduced, git bisect just might be your new best friend. Let’s pretend we’ve got the following set of commits.

$ git log --oneline --reverse
9a7ba42 We know everything is great here 😄
01f0396 Everything is still 👌
33f470a Oh no! A bug was introduced here 😬
9f676bb (HEAD -> master) The bug still exists 🙁

We know that the world was once okay, and that it isn’t now. Something changed. If only we could find out when things broke. git bisect to the rescue!

Let’s do this!

First things first, we need to tell Git that we’re ready to start.

git bisect start

Next, we’ll give Git the sha of a commit which we know is in a bad state. Most of the time this will be the latest commit (HEAD). In the example above, we know there’s a bug as recently as 9f676bb. Let’s use that.

git bisect bad 9f676bb

Next, we need to tell Git the last known good state. Since we know our bug wasn’t around in 9a7ba42, we’ll use that.

git bisect good 9a7ba42

Now comes the exciting part! We’ll provide a command which will be used by Git to find the commit which introduced the bug. For simplicity’s sake, I’ll use rspec, but it can be anything so long as it returns a non-zero exit code when there is a problem, and a zero exit code when everything is okay.

git bisect run bundle exec rspec

git bisect will do its thing, performing a binary search to find the offending commit. You should see something like this:

What if you have a bug, but no test to surface it? Git still has you covered! If you can’t write a test, you can walk Git through the process by performing manual tests then feeding Git the result by issuing git bisect bad or git bisect good (no sha). It’s a more manual process, but the result will be the same!

Important!

It’s important that you run git bisect reset when you’re done, or you’ll find yourself without a branch.

I learned a new bit of Git functionality this week while pairing with a co-worker, namely the -N flag for git add. Whenever you create a new file in a Git repository, it is considered “untracked” until you make Git aware of it.

Your branch is up to date with 'origin/master'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        file.ext

git add -N¹ effectively tells Git to track the file. After issuing the command, the contents of file.txt will be available to Git as if they were introduced in a previous commit. You’ll be able to diff, grep and mv file.txt (and more!) without actually having to stage the file.

A new alias

To follow up on my last post, Semantic Git Aliases, I created an alias that I feel more aptly describes this operation, git track. I’ve been using the alias for a couple of days now and have found it both useful and intuitive. I hope you’ll agree.

[alias]
  track = add -N

From the git add man page:

 -N, --intent-to-add
   Record only the fact that the path will be added later. An entry
   for the path is placed in the index with no content. This is useful
   for, among other things, showing the unstaged content of such files
   with git diff and committing them with git commit -a.

TL;DR

[alias]
  uncommit = reset --soft HEAD^
  unstage = reset
  staged = diff --cached
  ctags = "!.git/hooks/ctags"

uncommit

As of the time of writing, a question on StackOverflow named “How to uncommit my last commit in Git” had been upvoted 666 times, and its accepted answer had been upvoted 1068 times. The title alone suggests what users are trying to do. They’re just not sure how to accomplish it. The answer is to use git reset --soft HEAD^, which, if you spend some time thinking about it, makes sense. But don’t make me think.

Aliasing the command to uncommit has taken the mental overhead out of the equation. And since I’m not searching for the correct syntax every time, it also saves me time. It’s been all upside.

unstage

Here’s what I see every time I issue git status:

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

“Use … to unstage”. While I don’t need to open up my browser to look up the syntax, I still have to translate the command and arguments to understand its purpose. Aliasing to unstage ends up adding a keystroke, but I find it reduces the mental energy spent on the task. Thanks to Thoughtbot for sharing and making my Git experience better!

staged

I try to be very intentional about my commits, grouping alike changes to ensure that the story I’m telling to the reviewer (and future maintainers) is coherent. In the process of preparing a commit I often look at the current diff, as well as what has already been staged. I used to have git diff --cached memorized for this purpose, but aliasing the command has made it so much more friendly to use.

While uncommit and unstage are used occasionally, I use staged all the time.

ctags

This alias sheds less light on what Git itself is doing, but I find it useful and hope others will as well. It relies on Tim Pope’s Effortless Ctags with Git setup, which I highly recommend if you’re a Vim user. With this alias, you can re-index your codebase without relying on a Git hook.

I hope you find these aliases as helpful as I do, not for their ability to save keystrokes, but for how accessible they make some of Git’s powerful features.

If you’re familiar with variable ownership in Ruby, you can probably see where this is going. Since each class is an instance of Class, an instance variable in a class method belongs to the class. Each time that method is called, the exact same instance variable is referenced. In a multi-threaded context, this can have some very undesirable side effects.

I’ll create a contrived scenario to illustrate. Say we’re a bank and we’ve got customers who want their balance emailed to them each night. We assume customers that carry no balance shouldn’t get emails. We’ve created BalanceNotice to handle this.

class BalanceNotice
  def self.mail(email, balance)
    @balance = balance.to_f

    if should_email?
      BalanceMailer.mail(to: email, subject: "Your balance is #{@balance}")
    end
  end

  def should_email?
    !@balance.zero?
  end
end

Things are looking great: tests pass, the product team loves it, it looks great in the staging environment. Time to ship! Then the first night it’s out in its new multi-threaded production environment calls start coming in from frantic customers. “Someone must have stolen my identity.” “Freeze my account, now!” Something is wrong. They’re receiving emails with balances from other accounts.

Here’s how that could happen:

 BalanceNotice.mail("joe@joe.com", 50) |
     @balance = 50.0                   |
     should_email? => true             |
                                       | BalanceNotice.mail("ann@ann.com", 9000)
                                       |     @balance = 9000.0
     BalanceMailer.mail(               |
       "joe@joe.com",                  |
       "Your balance is $9000.0"       |
     )                                 |
                                       |     should_email? => true
                                       |     BalanceMailer.mail(
                                       |       "ann@ann.com",
                                       |       "Your balance is $9000.0"
                                       |     )

While Ann is happy with this new feature, Joe is ecstatic (for now). BalanceNotice.mail was called with his balance as an argument, but before his email was sent @balance was re-bound to Ann’s balance.

Unless you anticipate this behavior, this bug might be hard to find. However, it is pretty simple to fix. By replacing the class instance variable (@balance) with a local variable (balance), and passing that local variable to should_email? as an argument, sanity is returned.

class BalanceNotice
  def self.mail(email, balance)
    balance = balance.to_f

    if should_email?(balance)
      BalanceMailer.mail(to: email, subject: "Your balance is #{balance}")
    end
  end

  def should_email?(balance)
    !balance.zero?
  end
end

Now each time .mail is called balance will be local to that call. Joe will get Joe’s balance (with great disappointment) and Ann will continue to get Ann’s balance.