git/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 depending
  16 on the subcommand:
  17
  18  git bisect start [<bad> [<good>...]] [--] [<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  git bisect run <cmd>...
  26
  27 This command uses 'git-rev-list --bisect' option to help drive the
  28 binary search process to find which change introduced a bug, given an
  29 old "good" commit object name and a later "bad" commit object name.
  30
  31 Basic bisect commands: start, bad, good
  32 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  33
  34 The way you use it is:
  35
  36 ------------------------------------------------
  37 $ git bisect start
  38 $ git bisect bad                 # Current version is bad
  39 $ git bisect good v2.6.13-rc2    # v2.6.13-rc2 was the last version
  40                                  # tested that was good
  41 ------------------------------------------------
  42
  43 When you give at least one bad and one good versions, it will bisect
  44 the revision tree and say something like:
  45
  46 ------------------------------------------------
  47 Bisecting: 675 revisions left to test after this
  48 ------------------------------------------------
  49
  50 and check out the state in the middle. Now, compile that kernel, and
  51 boot it. Now, let's say that this booted kernel works fine, then just
  52 do
  53
  54 ------------------------------------------------
  55 $ git bisect good                       # this one is good
  56 ------------------------------------------------
  57
  58 which will now say
  59
  60 ------------------------------------------------
  61 Bisecting: 337 revisions left to test after this
  62 ------------------------------------------------
  63
  64 and you continue along, compiling that one, testing it, and depending
  65 on whether it is good or bad, you say "git bisect good" or "git bisect
  66 bad", and ask for the next bisection.
  67
  68 Until you have no more left, and you'll have been left with the first
  69 bad kernel rev in "refs/bisect/bad".
  70
  71 Bisect reset
  72 ~~~~~~~~~~~~
  73
  74 Oh, and then after you want to reset to the original head, do a
  75
  76 ------------------------------------------------
  77 $ git bisect reset
  78 ------------------------------------------------
  79
  80 to get back to the master branch, instead of being in one of the
  81 bisection branches ("git bisect start" will do that for you too,
  82 actually: it will reset the bisection state, and before it does that
  83 it checks that you're not using some old bisection branch).
  84
  85 Bisect visualize
  86 ~~~~~~~~~~~~~~~~
  87
  88 During the bisection process, you can say
  89
  90 ------------
  91 $ git bisect visualize
  92 ------------
  93
  94 to see the currently remaining suspects in `gitk`.
  95
  96 Bisect log and bisect replay
  97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98
  99 The good/bad input is logged, and
 100
 101 ------------
 102 $ git bisect log
 103 ------------
 104
 105 shows what you have done so far. You can truncate its output somewhere
 106 and save it in a file, and run
 107
 108 ------------
 109 $ git bisect replay that-file
 110 ------------
 111
 112 if you find later you made a mistake telling good/bad about a
 113 revision.
 114
 115 Avoiding to test a commit
 116 ~~~~~~~~~~~~~~~~~~~~~~~~~
 117
 118 If in a middle of bisect session, you know what the bisect suggested
 119 to try next is not a good one to test (e.g. the change the commit
 120 introduces is known not to work in your environment and you know it
 121 does not have anything to do with the bug you are chasing), you may
 122 want to find a near-by commit and try that instead.
 123
 124 It goes something like this:
 125
 126 ------------
 127 $ git bisect good/bad                   # previous round was good/bad.
 128 Bisecting: 337 revisions left to test after this
 129 $ git bisect visualize                  # oops, that is uninteresting.
 130 $ git reset --hard HEAD~3               # try 3 revs before what
 131                                         # was suggested
 132 ------------
 133
 134 Then compile and test the one you chose to try. After that, tell
 135 bisect what the result was as usual.
 136
 137 Cutting down bisection by giving more parameters to bisect start
 138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 139
 140 You can further cut down the number of trials if you know what part of
 141 the tree is involved in the problem you are tracking down, by giving
 142 paths parameters when you say `bisect start`, like this:
 143
 144 ------------
 145 $ git bisect start -- arch/i386 include/asm-i386
 146 ------------
 147
 148 If you know beforehand more than one good commits, you can narrow the
 149 bisect space down without doing the whole tree checkout every time you
 150 give good commits. You give the bad revision immediately after `start`
 151 and then you give all the good revisions you have:
 152
 153 ------------
 154 $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
 155                    # v2.6.20-rc6 is bad
 156                    # v2.6.20-rc4 and v2.6.20-rc1 are good
 157 ------------
 158
 159 Bisect run
 160 ~~~~~~~~~~
 161
 162 If you have a script that can tell if the current source code is good
 163 or bad, you can automatically bisect using:
 164
 165 ------------
 166 $ git bisect run my_script
 167 ------------
 168
 169 Note that the "run" script (`my_script` in the above example) should
 170 exit with code 0 in case the current source code is good and with a
 171 code between 1 and 127 (included) in case the current source code is
 172 bad.
 173
 174 Any other exit code will abort the automatic bisect process. (A
 175 program that does "exit(-1)" leaves $? = 255, see exit(3) manual page,
 176 the value is chopped with "& 0377".)
 177
 178 You may often find that during bisect you want to have near-constant
 179 tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or
 180 "revision that does not have this commit needs this patch applied to
 181 work around other problem this bisection is not interested in")
 182 applied to the revision being tested.
 183
 184 To cope with such a situation, after the inner git-bisect finds the
 185 next revision to test, with the "run" script, you can apply that tweak
 186 before compiling, run the real test, and after the test decides if the
 187 revision (possibly with the needed tweaks) passed the test, rewind the
 188 tree to the pristine state.  Finally the "run" script can exit with
 189 the status of the real test to let "git bisect run" command loop to
 190 know the outcome.
 191
 192 Author
 193 ------
 194 Written by Linus Torvalds <torvalds@osdl.org>
 195
 196 Documentation
 197 -------------
 198 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 199
 200 GIT
 201 ---
 202 Part of the gitlink:git[7] suite