Documentation/git-bisect.txt

   1 git-bisect(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-bisect - Find the change that introduced a bug
   7
   8
   9 SYNOPSIS
  10 --------
  11 'git bisect' start
  12 'git bisect' bad <rev>
  13 'git bisect' good <rev>
  14 'git bisect' reset [<branch>]
  15 'git bisect' visualize
  16 'git bisect' replay <logfile>
  17 'git bisect' log
  18
  19 DESCRIPTION
  20 -----------
  21 This command uses 'git-rev-list --bisect' option to help drive
  22 the binary search process to find which change introduced a bug,
  23 given an old "good" commit object name and a later "bad" commit
  24 object name.
  25
  26 The way you use it is:
  27
  28 ------------------------------------------------
  29 git bisect start
  30 git bisect bad                  # Current version is bad
  31 git bisect good v2.6.13-rc2     # v2.6.13-rc2 was the last version
  32                                 # tested that was good
  33 ------------------------------------------------
  34
  35 When you give at least one bad and one good versions, it will
  36 bisect the revision tree and say something like:
  37
  38 ------------------------------------------------
  39 Bisecting: 675 revisions left to test after this
  40 ------------------------------------------------
  41
  42 and check out the state in the middle. Now, compile that kernel, and boot
  43 it. Now, let's say that this booted kernel works fine, then just do
  44
  45 ------------------------------------------------
  46 git bisect good                 # this one is good
  47 ------------------------------------------------
  48
  49 which will now say
  50
  51 ------------------------------------------------
  52 Bisecting: 337 revisions left to test after this
  53 ------------------------------------------------
  54
  55 and you continue along, compiling that one, testing it, and depending on
  56 whether it is good or bad, you say "git bisect good" or "git bisect bad",
  57 and ask for the next bisection.
  58
  59 Until you have no more left, and you'll have been left with the first bad
  60 kernel rev in "refs/bisect/bad".
  61
  62 Oh, and then after you want to reset to the original head, do a
  63
  64 ------------------------------------------------
  65 git bisect reset
  66 ------------------------------------------------
  67
  68 to get back to the master branch, instead of being in one of the bisection
  69 branches ("git bisect start" will do that for you too, actually: it will
  70 reset the bisection state, and before it does that it checks that you're
  71 not using some old bisection branch).
  72
  73 During the bisection process, you can say
  74
  75         git bisect visualize
  76
  77 to see the currently remaining suspects in `gitk`.
  78
  79 The good/bad you told the command is logged, and `git bisect
  80 log` shows what you have done so far.  You can truncate its
  81 output somewhere and save it in a file, and run
  82
  83         git bisect replay that-file
  84
  85 if you find later you made a mistake telling good/bad about a
  86 revision.
  87
  88
  89 Author
  90 ------
  91 Written by Linus Torvalds <torvalds@osdl.org>
  92
  93 Documentation
  94 --------------
  95 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
  96
  97 GIT
  98 ---
  99 Part of the gitlink:git[7] suite
 100