Documentation/git-bisect.txt

   1 git-bisect(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-bisect - Find the change that introduced a bug by binary search
   7
   8
   9 SYNOPSIS
  10 --------
  11 'git bisect' <subcommand> <options>
  12
  13 DESCRIPTION
  14 -----------
  15 The command takes various subcommands, and different options
  16 depending on the subcommand:
  17
  18  git bisect start [<paths>...]
  19  git bisect bad <rev>
  20  git bisect good <rev>
  21  git bisect reset [<branch>]
  22  git bisect visualize
  23  git bisect replay <logfile>
  24  git bisect log
  25
  26 This command uses 'git-rev-list --bisect' option to help drive
  27 the binary search process to find which change introduced a bug,
  28 given an old "good" commit object name and a later "bad" commit
  29 object name.
  30
  31 The way you use it is:
  32
  33 ------------------------------------------------
  34 $ git bisect start
  35 $ git bisect bad                        # Current version is bad
  36 $ git bisect good v2.6.13-rc2           # v2.6.13-rc2 was the last version
  37                                         # tested that was good
  38 ------------------------------------------------
  39
  40 When you give at least one bad and one good versions, it will
  41 bisect the revision tree and say something like:
  42
  43 ------------------------------------------------
  44 Bisecting: 675 revisions left to test after this
  45 ------------------------------------------------
  46
  47 and check out the state in the middle. Now, compile that kernel, and boot
  48 it. Now, let's say that this booted kernel works fine, then just do
  49
  50 ------------------------------------------------
  51 $ git bisect good                       # this one is good
  52 ------------------------------------------------
  53
  54 which will now say
  55
  56 ------------------------------------------------
  57 Bisecting: 337 revisions left to test after this
  58 ------------------------------------------------
  59
  60 and you continue along, compiling that one, testing it, and depending on
  61 whether it is good or bad, you say "git bisect good" or "git bisect bad",
  62 and ask for the next bisection.
  63
  64 Until you have no more left, and you'll have been left with the first bad
  65 kernel rev in "refs/bisect/bad".
  66
  67 Oh, and then after you want to reset to the original head, do a
  68
  69 ------------------------------------------------
  70 $ git bisect reset
  71 ------------------------------------------------
  72
  73 to get back to the master branch, instead of being in one of the bisection
  74 branches ("git bisect start" will do that for you too, actually: it will
  75 reset the bisection state, and before it does that it checks that you're
  76 not using some old bisection branch).
  77
  78 During the bisection process, you can say
  79
  80 ------------
  81 $ git bisect visualize
  82 ------------
  83
  84 to see the currently remaining suspects in `gitk`.
  85
  86 The good/bad input is logged, and `git bisect
  87 log` shows what you have done so far.  You can truncate its
  88 output somewhere and save it in a file, and run
  89
  90 ------------
  91 $ git bisect replay that-file
  92 ------------
  93
  94 if you find later you made a mistake telling good/bad about a
  95 revision.
  96
  97 If in a middle of bisect session, you know what the bisect
  98 suggested to try next is not a good one to test (e.g. the change
  99 the commit introduces is known not to work in your environment
 100 and you know it does not have anything to do with the bug you
 101 are chasing), you may want to find a near-by commit and try that
 102 instead.  It goes something like this:
 103
 104 ------------
 105 $ git bisect good/bad                   # previous round was good/bad.
 106 Bisecting: 337 revisions left to test after this
 107 $ git bisect visualize                  # oops, that is uninteresting.
 108 $ git reset --hard HEAD~3               # try 3 revs before what
 109                                         # was suggested
 110 ------------
 111
 112 Then compile and test the one you chose to try.  After that,
 113 tell bisect what the result was as usual.
 114
 115 You can further cut down the number of trials if you know what
 116 part of the tree is involved in the problem you are tracking
 117 down, by giving paths parameters when you say `bisect start`,
 118 like this:
 119
 120 ------------
 121 $ git bisect start arch/i386 include/asm-i386
 122 ------------
 123
 124
 125 Author
 126 ------
 127 Written by Linus Torvalds <torvalds@osdl.org>
 128
 129 Documentation
 130 -------------
 131 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 132
 133 GIT
 134 ---
 135 Part of the gitlink:git[7] suite
 136