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

   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 last)
  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