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 [<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 path parameter 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 Bisect run
 149 ~~~~~~~~~~
 150
 151 If you have a script that can tell if the current source code is good
 152 or bad, you can automatically bisect using:
 153
 154 ------------
 155 $ git bisect run my_script
 156 ------------
 157
 158 Note that the "run" script (`my_script` in the above example) should
 159 exit with code 0 in case the current source code is good and with a
 160 code between 1 and 127 (included) in case the current source code is
 161 bad.
 162
 163 Any other exit code will abort the automatic bisect process. (A
 164 program that does "exit(-1)" leaves $? = 255, see exit(3) manual page,
 165 the value is chopped with "& 0377".)
 166
 167 You may often find that during bisect you want to have near-constant
 168 tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or
 169 "revision that does not have this commit needs this patch applied to
 170 work around other problem this bisection is not interested in")
 171 applied to the revision being tested.
 172
 173 To cope with such a situation, after the inner git-bisect finds the
 174 next revision to test, with the "run" script, you can apply that tweak
 175 before compiling, run the real test, and after the test decides if the
 176 revision (possibly with the needed tweaks) passed the test, rewind the
 177 tree to the pristine state.  Finally the "run" script can exit with
 178 the status of the real test to let "git bisect run" command loop to
 179 know the outcome.
 180
 181 Author
 182 ------
 183 Written by Linus Torvalds <torvalds@osdl.org>
 184
 185 Documentation
 186 -------------
 187 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 188
 189 GIT
 190 ---
 191 Part of the gitlink:git[7] suite
 192