1From: Linus Torvalds <torvalds () osdl ! org> 2To: git@vger.kernel.org 3Date: 2005-11-08 1:31:34 4Subject: Real-life kernel debugging scenario 5Abstract: Short-n-sweet, Linus tells us how to leverage `git-bisect` to perform 6 bug isolation on a repository where "good" and "bad" revisions are known 7 in order to identify a suspect commit. 8 9 10How To Use git-bisect To Isolate a Bogus Commit 11=============================================== 12 13The way to use "git bisect" couldn't be easier. 14 15Figure out what the oldest bad state you know about is (that's usually the 16head of "master", since that's what you just tried to boot and failed at). 17Also, figure out the most recent known-good commit (usually the _previous_ 18kernel you ran: and if you've only done a single "pull" in between, it 19will be ORIG_HEAD). 20 21Then do 22 23 git bisect start 24 git bisect bad master <- mark "master" as the bad state 25 git bisect good ORIG_HEAD <- mark ORIG_HEAD as good (or 26 whatever other known-good 27 thing you booted last) 28 29and at this point "git bisect" will churn for a while, and tell you what 30the mid-point between those two commits are, and check that state out as 31the head of the new "bisect" branch. 32 33Compile and reboot. 34 35If it's good, just do 36 37 git bisect good <- mark current head as good 38 39otherwise, reboot into a good kernel instead, and do (surprise surprise, 40git really is very intuitive): 41 42 git bisect bad <- mark current head as bad 43 44and whatever you do, git will select a new half-way point. Do this for a 45while, until git tells you exactly which commit was the first bad commit. 46That's your culprit. 47 48It really works wonderfully well, except for the case where there was 49_another_ commit that broke something in between, like introduced some 50stupid compile error. In that case you should not mark that commit good or 51bad: you should try to find another commit close-by, and do a "git reset 52--hard <newcommit>" to try out _that_ commit instead, and then test that 53instead (and mark it good or bad). 54 55You can do "git bisect visualize" while you do all this to see what's 56going on by starting up gitk on the bisection range. 57 58Finally, once you've figured out exactly which commit was bad, you can 59then go back to the master branch, and try reverting just that commit: 60 61 git checkout master 62 git revert <bad-commit-id> 63 64to verify that the top-of-kernel works with that single commit reverted. 65