If you’re reading this, you’re an avid user of git, have made tons of commits and now you’re trying to find..

where the hell did the bug get introduced ?

git-bisect is a perfect tool to find that. To explain this awesome tool, I’ve created a small demo-repository which has only one file text.txt. In this file, I’ve incrementally added a, b, c, d and so on in each commit.

This is how my file text.txt looks like

[rutu@ruturaj-vartak git-bisect-demo]$ cat text.txt 
a
z
c
d
e
f
g
h
i
j
k
l
m
n

My git graph/log looks as below

If you are wondering what is “git g” its just an alias, following is my ~/.gitconfig

[rutu@ruturaj-vartak git-bisect-demo]$ cat ~/.gitconfig 
[alias]
	ci = commit
	st = status
	di = diff
	co = checkout
	k = !gitk --all
	g = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --all
	d = difftool
[color]
	ui = true
[user]
	name = Ruturaj K. Vartak
	email = ruturaj@localhost
[diff]
	tool = vimdiff

To simulate a bug, somewhere in my code, I’ve replaced b with z. Now the with the current state of my code, I’ve got to find where and who introduced z in my code ?. Lets begin

git-bisect uses BST style division and search mechanism. So lets start.

1. Start with a command,
$ git bisect start
2. Now its necessary to tell git, that where was the code good and bad. Obviously my code was good at revision b162893 and the HEAD or 20bacecis now bad. So ..
   1. $ git bisect good b162893
   2. $ git bisect bad 20bacec

   Now if you check the git graph…
   
   
   Notice how git has divided this history into 2 parts, and the HEAD now points to the partitioning commit fa70446.

   We can now cat the file and see if the bug was introduced.

   [rutu@ruturaj-vartak git-bisect-demo]$ cat text.txt 
   a
   b
   c
   d
   e
   f
   g
   h

   As you see, the bug still has not been introduced, so lets tell git that this commit is GOOD

3. $ git bisect good
   Now lets look how the graph looks
   
   
   The head is now d126a8f, the half between 20bacec and fa70446 and lets cat our file, text.txt

   [rutu@ruturaj-vartak git-bisect-demo]$ cat text.txt 
   a
   z
   c
   d
   e
   f
   g
   h
   i
   j
   k

   Wohoo ! our bug is existing here, but we don’t know if it was added in b38e6d7, df4f3bc or the HEAD – d126a8f

4. So we now tell git, that this is BAD commit
   $ git bisect bad
   Now lets look at our graph,
   
   
   It has made another division, HEAD now pointing to df4f3bc
5. Lets see if this HEAD is GOOD or BAD,

   [rutu@ruturaj-vartak git-bisect-demo]$ cat text.txt 
   a
   b
   c
   d
   e
   f
   g
   h
   i
   j

   Hey !!! The bug is non-existent over here. Lets tell git the good news

   $ git bisect good
   And this is what it returns us back

   [rutu@ruturaj-vartak git-bisect-demo]$ git bisect good
   d126a8fbd75cbf5e015228f0411d205745a77e05 is the first bad commit
   commit d126a8fbd75cbf5e015228f0411d205745a77e05
   Author: Ruturaj K. Vartak 
   Date:   Sat Jul 7 12:32:04 2012 +0530
   
       added k
   
   :100644 100644 92dfa216416a1ac944633ab674568f8bae139d95 261ccd63acaba8ae42219a40579a9acec61f05d0 M	text.txt

   Since there were no commits between our last found BAD commit – d126a8f and our current HEAD – df4f3bc, git has determined the bug was introduced in d126a8f. It throws a complete info stack of what it has for that commit.

   This is how our final graph looks like
   
   
   Note: there is nothing left to check between d126a8f(BAD) and df4f3bc(GOOD)

6. The last thing to do, is reset everything with
   git bisect reset
   Which leaves a clean state

   [rutu@ruturaj-vartak git-bisect-demo]$ git bisect reset
   Previous HEAD position was df4f3bc... added j
   Switched to branch 'master'
   [rutu@ruturaj-vartak git-bisect-demo]$ git g
   * 20bacec - (HEAD, master) added n (3 hours ago) 
   * c7edac3 - added m (3 hours ago) 
   * 83a34bc - added l (3 hours ago) 
   * d126a8f - added k (3 hours ago) 
   * df4f3bc - added j (3 hours ago) 
   * b38e6d7 - added i (3 hours ago) 
   * fa70446 - added h (3 hours ago) 
   * e4efb05 - added g (3 hours ago) 
   * 8fe6f2a - added f (3 hours ago) 
   * 96381ba - added e (3 hours ago) 
   * a07ce18 - added d (3 hours ago) 
   * 0b824e0 - added c (3 hours ago) 
   * b162893 - added b (3 hours ago) 
   * 7a60f8d - added a (3 hours ago)

Automating git bisect

Even though the above method looks easy, it could be painful if you’re going through 100s of commits. git has an automated way as well, using the git bisect run. Lets look how we can search our above code for bugs using the automated way

For git bisect run cmd, It needs an argument of a command that’ll do the search of bug in the script and return exit code 0 for GOOD or 1 for BAD.

Lets create a simple bug-finder.sh script that will grep for b, if grep finds, it’ll give exit status as 0, or else 1. We’ll capture the exit status of grep and throw as exit status of our script. We’ll place our bug-finder.sh in root folder of our repo.

Here is the script, Make sure you chmod +x bug-finder.sh


[rutu@ruturaj-vartak git-bisect-demo]$ cat bug-finder.sh 
#!/bin/bash
grep "b" text.txt
exitCode=$?
if [ $exitCode -eq 0 ]; then
	exit 0;
else
	exit 1;
fi

Lets begin, steps stay the same…

1. $ git bisect start
2. $ git bisect good b162893
3. $ git bisect bad 20bacec
4. Now, the magic –
   $ git bisect run ./bug-finder.sh
   The output is as follows – git successfully finding the bug

[rutu@ruturaj-vartak git-bisect-demo]$ git bisect run ./bug-finder.sh 
running ./bug-finder.sh
b
Bisecting: 2 revisions left to test after this (roughly 2 steps)
[d126a8fbd75cbf5e015228f0411d205745a77e05] added k
running ./bug-finder.sh
Bisecting: 0 revisions left to test after this (roughly 1 step)
[df4f3bc1e079bc75afd922726c719e16d1e4efdf] added j
running ./bug-finder.sh
b
d126a8fbd75cbf5e015228f0411d205745a77e05 is the first bad commit
commit d126a8fbd75cbf5e015228f0411d205745a77e05
Author: Ruturaj K. Vartak 
Date:   Sat Jul 7 12:32:04 2012 +0530

    added k

:100644 100644 92dfa216416a1ac944633ab674568f8bae139d95 261ccd63acaba8ae42219a40579a9acec61f05d0 M	text.txt
bisect run success

There it is, simply and cool. Ofcourse in this case a lot depends how and what you’ve coded in ur bug-finder.sh. A bug in this script will just fool git.

Update: You can clone the git-bisect-demo repository