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.
- Start with a command,
$ git bisect start - Now its necessary to tell git, that where was the code good and bad. Obviously my code was good at revision
b162893and theHEADor20bacecis now bad. So ..$ git bisect good b162893$ 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 commitfa70446.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
$ 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
- 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 - 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.txtSince 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) - 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…
$ git bisect start$ git bisect good b162893$ git bisect bad 20bacec- 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
