Documentation/git-bisect.txt

   1 git-bisect(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-bisect - Find by binary search the change that introduced a bug
   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 help
  19  git bisect start [<bad> [<good>...]] [--] [<paths>...]
  20  git bisect bad [<rev>]
  21  git bisect good [<rev>...]
  22  git bisect skip [(<rev>|<range>)...]
  23  git bisect reset [<branch>]
  24  git bisect visualize
  25  git bisect replay <logfile>
  26  git bisect log
  27  git bisect run <cmd>...
  28
  29 This command uses 'git rev-list --bisect' to help drive the
  30 binary search process to find which change introduced a bug, given an
  31 old "good" commit object name and a later "bad" commit object name.
  32
  33 Getting help
  34 ~~~~~~~~~~~~
  35
  36 Use "git bisect" to get a short usage description, and "git bisect
  37 help" or "git bisect -h" to get a long usage description.
  38
  39 Basic bisect commands: start, bad, good
  40 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  41
  42 Using the Linux kernel tree as an example, basic use of the bisect
  43 command is as follows:
  44
  45 ------------------------------------------------
  46 $ git bisect start
  47 $ git bisect bad                 # Current version is bad
  48 $ git bisect good v2.6.13-rc2    # v2.6.13-rc2 was the last version
  49                                  # tested that was good
  50 ------------------------------------------------
  51
  52 When you have specified at least one bad and one good version, the
  53 command bisects the revision tree and outputs something similar to:
  54
  55 ------------------------------------------------
  56 Bisecting: 675 revisions left to test after this
  57 ------------------------------------------------
  58
  59 and then checks out the state in the middle. You would now compile
  60 that kernel and boot it. If the booted kernel works correctly, you
  61 would then issue the following command:
  62
  63 ------------------------------------------------
  64 $ git bisect good                       # this one is good
  65 ------------------------------------------------
  66
  67 which would then output something similar to:
  68
  69 ------------------------------------------------
  70 Bisecting: 337 revisions left to test after this
  71 ------------------------------------------------
  72
  73 and you continue along, compiling that one, testing it, and depending
  74 on whether it is good or bad issuing the command "git bisect good"
  75 or "git bisect bad" to ask for the next bisection.
  76
  77 Eventually there will be no more revisions left to bisect, and you
  78 will have been left with the first bad kernel revision in "refs/bisect/bad".
  79
  80 Bisect reset
  81 ~~~~~~~~~~~~
  82
  83 To return to the original head after a bisect session, you issue the
  84 command:
  85
  86 ------------------------------------------------
  87 $ git bisect reset
  88 ------------------------------------------------
  89
  90 This resets the tree to the original branch instead of being on the
  91 bisection commit ("git bisect start" will also do that, as it resets
  92 the bisection state).
  93
  94 Bisect visualize
  95 ~~~~~~~~~~~~~~~~
  96
  97 During the bisection process, you issue the command:
  98
  99 ------------
 100 $ git bisect visualize
 101 ------------
 102
 103 to see the currently remaining suspects in 'gitk'.  `view` may also
 104 be used as a synonym for `visualize`.
 105
 106 If the 'DISPLAY' environment variable is not set, 'git log' is used
 107 instead.  You can also give command line options such as `-p` and
 108 `--stat`.
 109
 110 ------------
 111 $ git bisect view --stat
 112 ------------
 113
 114 Bisect log and bisect replay
 115 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 116
 117 After having marked revisions as good or bad, then:
 118
 119 ------------
 120 $ git bisect log
 121 ------------
 122
 123 shows what you have done so far. If you discover that you made a mistake
 124 in specifying the status of a revision, you can save the output of this
 125 command to a file, edit it to remove the incorrect entries, and then issue
 126 the following commands to return to a corrected state:
 127
 128 ------------
 129 $ git bisect reset
 130 $ git bisect replay that-file
 131 ------------
 132
 133 Avoiding testing a commit
 134 ~~~~~~~~~~~~~~~~~~~~~~~~~
 135
 136 If in the middle of a bisect session, you know that the next suggested
 137 revision is not a good one to test (e.g. the change the commit
 138 introduces is known not to work in your environment and you know it
 139 does not have anything to do with the bug you are chasing), you may
 140 want to find a nearby commit and try that instead.
 141
 142 For example:
 143
 144 ------------
 145 $ git bisect good/bad                   # previous round was good or bad.
 146 Bisecting: 337 revisions left to test after this
 147 $ git bisect visualize                  # oops, that is uninteresting.
 148 $ git reset --hard HEAD~3               # try 3 revisions before what
 149                                         # was suggested
 150 ------------
 151
 152 Then compile and test the chosen revision. Afterwards the revision
 153 is marked as good or bad in the usual manner.
 154
 155 Bisect skip
 156 ~~~~~~~~~~~~
 157
 158 Instead of choosing by yourself a nearby commit, you can ask git
 159 to do it for you by issuing the command:
 160
 161 ------------
 162 $ git bisect skip                 # Current version cannot be tested
 163 ------------
 164
 165 But computing the commit to test may be slower afterwards and git may
 166 eventually not be able to tell the first bad commit among a bad commit
 167 and one or more skipped commits.
 168
 169 You can even skip a range of commits, instead of just one commit,
 170 using the "'<commit1>'..'<commit2>'" notation. For example:
 171
 172 ------------
 173 $ git bisect skip v2.5..v2.6
 174 ------------
 175
 176 would mean that no commit between `v2.5` excluded and `v2.6` included
 177 can be tested.
 178
 179 Note that if you also want to skip the first commit of the range you
 180 would issue the command:
 181
 182 ------------
 183 $ git bisect skip v2.5 v2.5..v2.6
 184 ------------
 185
 186 and the commit pointed to by `v2.5` would also be skipped.
 187
 188 Cutting down bisection by giving more parameters to bisect start
 189 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 190
 191 You can further cut down the number of trials, if you know what part of
 192 the tree is involved in the problem you are tracking down, by specifying
 193 path parameters when issuing the `bisect start` command, like this:
 194
 195 ------------
 196 $ git bisect start -- arch/i386 include/asm-i386
 197 ------------
 198
 199 If you know beforehand more than one good commit, you can narrow the
 200 bisect space down by specifying all of the good commits immediately after
 201 the bad commit when issuing the `bisect start` command:
 202
 203 ------------
 204 $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
 205                    # v2.6.20-rc6 is bad
 206                    # v2.6.20-rc4 and v2.6.20-rc1 are good
 207 ------------
 208
 209 Bisect run
 210 ~~~~~~~~~~
 211
 212 If you have a script that can tell if the current source code is good
 213 or bad, you can bisect by issuing the command:
 214
 215 ------------
 216 $ git bisect run my_script
 217 ------------
 218
 219 Note that the script (`my_script` in the above example) should
 220 exit with code 0 if the current source code is good, and exit with a
 221 code between 1 and 127 (inclusive), except 125, if the current
 222 source code is bad.
 223
 224 Any other exit code will abort the bisect process. It should be noted
 225 that a program that terminates via "exit(-1)" leaves $? = 255, (see the
 226 exit(3) manual page), as the value is chopped with "& 0377".
 227
 228 The special exit code 125 should be used when the current source code
 229 cannot be tested. If the script exits with this code, the current
 230 revision will be skipped (see `git bisect skip` above).
 231
 232 You may often find that during a bisect session you want to have
 233 temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a
 234 header file, or "revision that does not have this commit needs this
 235 patch applied to work around another problem this bisection is not
 236 interested in") applied to the revision being tested.
 237
 238 To cope with such a situation, after the inner 'git bisect' finds the
 239 next revision to test, the script can apply the patch
 240 before compiling, run the real test, and afterwards decide if the
 241 revision (possibly with the needed patch) passed the test and then
 242 rewind the tree to the pristine state.  Finally the script should exit
 243 with the status of the real test to let the "git bisect run" command loop
 244 determine the eventual outcome of the bisect session.
 245
 246 EXAMPLES
 247 --------
 248
 249 * Automatically bisect a broken build between v1.2 and HEAD:
 250 +
 251 ------------
 252 $ git bisect start HEAD v1.2 --      # HEAD is bad, v1.2 is good
 253 $ git bisect run make                # "make" builds the app
 254 ------------
 255
 256 * Automatically bisect a broken test suite:
 257 +
 258 ------------
 259 $ cat ~/test.sh
 260 #!/bin/sh
 261 make || exit 125                   # this skips broken builds
 262 make test                          # "make test" runs the test suite
 263 $ git bisect start v1.3 v1.1 --    # v1.3 is bad, v1.1 is good
 264 $ git bisect run ~/test.sh
 265 ------------
 266 +
 267 Here we use a "test.sh" custom script. In this script, if "make"
 268 fails, we skip the current commit.
 269 +
 270 It is safer to use a custom script outside the repository to prevent
 271 interactions between the bisect, make and test processes and the
 272 script.
 273 +
 274 "make test" should "exit 0", if the test suite passes, and
 275 "exit 1" otherwise.
 276
 277 * Automatically bisect a broken test case:
 278 +
 279 ------------
 280 $ cat ~/test.sh
 281 #!/bin/sh
 282 make || exit 125                     # this skips broken builds
 283 ~/check_test_case.sh                 # does the test case passes ?
 284 $ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
 285 $ git bisect run ~/test.sh
 286 ------------
 287 +
 288 Here "check_test_case.sh" should "exit 0" if the test case passes,
 289 and "exit 1" otherwise.
 290 +
 291 It is safer if both "test.sh" and "check_test_case.sh" scripts are
 292 outside the repository to prevent interactions between the bisect,
 293 make and test processes and the scripts.
 294
 295 Author
 296 ------
 297 Written by Linus Torvalds <torvalds@osdl.org>
 298
 299 Documentation
 300 -------------
 301 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 302
 303 GIT
 304 ---
 305 Part of the linkgit:git[1] suite