Add bug isolation howto, scraped from Linus.
Signed-off-by: Jon Loeliger <jdl@freescale.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
Jon Loeliger committed
Nov 7, 2005 at 20:45 UTC
b2d09f063a01b429fe1e8d5179d00f3938ec598b
1 file changed
+65
Documentation/howto/isolate-bugs-with-bisect.txt
new
+65
@@ -0,0 +1,65 @@
1
+From: Linus Torvalds <torvalds () osdl ! org>
2
+To: git@vger.kernel.org
3
+Date: 2005-11-08 1:31:34
4
+Subject: Real-life kernel debugging scenario
5
+Abstract: 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
+
10
+How To Use git-bisect To Isolate a Bogus Commit
11
+===============================================
12
+
13
+The way to use "git bisect" couldn't be easier.
14
+
15
+Figure out what the oldest bad state you know about is (that's usually the
16
+head of "master", since that's what you just tried to boot and failed at).
17
+Also, figure out the most recent known-good commit (usually the _previous_
18
+kernel you ran: and if you've only done a single "pull" in between, it
19
+will be ORIG_HEAD).
20
+
21
+Then 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 laste)
28
+
29
+and at this point "git bisect" will churn for a while, and tell you what
30
+the mid-point between those two commits are, and check that state out as
31
+the head of the bew "bisect" branch.
32
+
33
+Compile and reboot.
34
+
35
+If it's good, just do
36
+
37
+ git bisect good <- mark current head as good
38
+
39
+otherwise, reboot into a good kernel instead, and do (surprise surprise,
40
+git really is very intuitive):
41
+
42
+ git bisect bad <- mark current head as bad
43
+
44
+and whatever you do, git will select a new half-way point. Do this for a
45
+while, until git tells you exactly which commit was the first bad commit.
46
+That's your culprit.
47
+
48
+It really works wonderfully well, except for the case where there was
49
+_another_ commit that broke something in between, like introduced some
50
+stupid compile error. In that case you should not mark that commit good or
51
+bad: 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
53
+instead (and mark it good or bad).
54
+
55
+You can do "git bisect visualize" while you do all this to see what's
56
+going on by starting up gitk on the bisection range.
57
+
58
+Finally, once you've figured out exactly which commit was bad, you can
59
+then go back to the master branch, and try reverting just that commit:
60
+
61
+ git checkout master
62
+ git revert <bad-commit-id>
63
+
64
+to verify that the top-of-kernel works with that single commit reverted.
65
+