Jon Loeliger  committed b2d09f0

Add bug isolation howto, scraped from Linus.

Signed-off-by: Jon Loeliger <>
Signed-off-by: Junio C Hamano <>

  • Participants
  • Parent commits 390cb0c

Comments (0)

Files changed (1)

File Documentation/howto/isolate-bugs-with-bisect.txt

+From:	Linus Torvalds <torvalds () osdl ! org>
+Date:	2005-11-08 1:31:34
+Subject: Real-life kernel debugging scenario
+Abstract: Short-n-sweet, Linus tells us how to leverage `git-bisect` to perform
+	bug isolation on a repository where "good" and "bad" revisions are known
+	in order to identify a suspect commit.
+How To Use git-bisect To Isolate a Bogus Commit
+The way to use "git bisect" couldn't be easier.
+Figure out what the oldest bad state you know about is (that's usually the 
+head of "master", since that's what you just tried to boot and failed at). 
+Also, figure out the most recent known-good commit (usually the _previous_ 
+kernel you ran: and if you've only done a single "pull" in between, it 
+will be ORIG_HEAD).
+Then do
+	git bisect start
+	git bisect bad master		<- mark "master" as the bad state
+	git bisect good ORIG_HEAD	<- mark ORIG_HEAD as good (or
+					   whatever other known-good 
+					   thing you booted laste)
+and at this point "git bisect" will churn for a while, and tell you what 
+the mid-point between those two commits are, and check that state out as 
+the head of the bew "bisect" branch.
+Compile and reboot.
+If it's good, just do
+	git bisect good		<- mark current head as good
+otherwise, reboot into a good kernel instead, and do (surprise surprise, 
+git really is very intuitive):
+	git bisect bad		<- mark current head as bad
+and whatever you do, git will select a new half-way point. Do this for a 
+while, until git tells you exactly which commit was the first bad commit. 
+That's your culprit.
+It really works wonderfully well, except for the case where there was 
+_another_ commit that broke something in between, like introduced some 
+stupid compile error. In that case you should not mark that commit good or 
+bad: you should try to find another commit close-by, and do a "git reset 
+--hard <newcommit>" to try out _that_ commit instead, and then test that 
+instead (and mark it good or bad).
+You can do "git bisect visualize" while you do all this to see what's 
+going on by starting up gitk on the bisection range.
+Finally, once you've figured out exactly which commit was bad, you can 
+then go back to the master branch, and try reverting just that commit:
+	git checkout master
+	git revert <bad-commit-id>
+to verify that the top-of-kernel works with that single commit reverted.