@matheusbsbs / matheus-bagliano / commits / b2d09f063a
Fork 0

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 +