Bisect: implement "git bisect run <cmd>..." to automatically bisect.
[gitweb.git] / Documentation / git-bisect.txt
index 8a399703dc7d75c8ca3d170e6d18832a7ce8723b..b7cd715380442b5af6124e642cdbf0210594c889 100644 (file)
@@ -3,21 +3,27 @@ git-bisect(1)
 
 NAME
 ----
-git-bisect - Find the change that introduced a bug
+git-bisect - Find the change that introduced a bug by binary search
 
 
 SYNOPSIS
 --------
- 'git bisect' start
- 'git bisect' bad <rev>
- 'git bisect' good <rev>
- 'git bisect' reset [<branch>]
- 'git bisect' visualize
- 'git bisect' replay <logfile>
- 'git bisect' log
+'git bisect' <subcommand> <options> 
 
 DESCRIPTION
 -----------
+The command takes various subcommands, and different options
+depending on the subcommand:
+
+ git bisect start [<paths>...]
+ git bisect bad <rev>
+ git bisect good <rev>
+ git bisect reset [<branch>]
+ git bisect visualize
+ git bisect replay <logfile>
+ git bisect log
+ git bisect run <cmd>...
+
 This command uses 'git-rev-list --bisect' option to help drive
 the binary search process to find which change introduced a bug,
 given an old "good" commit object name and a later "bad" commit
@@ -26,10 +32,10 @@ object name.
 The way you use it is:
 
 ------------------------------------------------
-git bisect start
-git bisect bad                 # Current version is bad
-git bisect good v2.6.13-rc2    # v2.6.13-rc2 was the last version
-                               # tested that was good
+git bisect start
+$ git bisect bad                       # Current version is bad
+$ git bisect good v2.6.13-rc2          # v2.6.13-rc2 was the last version
+                                       # tested that was good
 ------------------------------------------------
 
 When you give at least one bad and one good versions, it will
@@ -43,7 +49,7 @@ and check out the state in the middle. Now, compile that kernel, and boot
 it. Now, let's say that this booted kernel works fine, then just do
 
 ------------------------------------------------
-git bisect good                        # this one is good
+$ git bisect good                      # this one is good
 ------------------------------------------------
 
 which will now say
@@ -62,7 +68,7 @@ kernel rev in "refs/bisect/bad".
 Oh, and then after you want to reset to the original head, do a
 
 ------------------------------------------------
-git bisect reset
+git bisect reset
 ------------------------------------------------
 
 to get back to the master branch, instead of being in one of the bisection
@@ -72,7 +78,9 @@ not using some old bisection branch).
 
 During the bisection process, you can say
 
-       git bisect visualize
+------------
+$ git bisect visualize
+------------
 
 to see the currently remaining suspects in `gitk`.
 
@@ -80,11 +88,69 @@ The good/bad input is logged, and `git bisect
 log` shows what you have done so far.  You can truncate its
 output somewhere and save it in a file, and run
 
-       git bisect replay that-file
+------------
+$ git bisect replay that-file
+------------
 
 if you find later you made a mistake telling good/bad about a
 revision.
 
+If in a middle of bisect session, you know what the bisect
+suggested to try next is not a good one to test (e.g. the change
+the commit introduces is known not to work in your environment
+and you know it does not have anything to do with the bug you
+are chasing), you may want to find a near-by commit and try that
+instead.  It goes something like this:
+
+------------
+$ git bisect good/bad                  # previous round was good/bad.
+Bisecting: 337 revisions left to test after this
+$ git bisect visualize                 # oops, that is uninteresting.
+$ git reset --hard HEAD~3              # try 3 revs before what
+                                       # was suggested
+------------
+
+Then compile and test the one you chose to try.  After that,
+tell bisect what the result was as usual.
+
+You can further cut down the number of trials if you know what
+part of the tree is involved in the problem you are tracking
+down, by giving paths parameters when you say `bisect start`,
+like this:
+
+------------
+$ git bisect start arch/i386 include/asm-i386
+------------
+
+If you have a script that can tell if the current
+source code is good or bad, you can automatically bisect using:
+
+------------
+$ git bisect run my_script
+------------
+
+Note that the "run" script (`my_script` in the above example)
+should exit with code 0 in
+case the current source code is good and with a code between 1 and 127
+(included) in case the current source code is bad.
+
+Any other exit code (a program that does "exit(-1)" leaves $? = 255,
+see exit(3) manual page, the value is chopped with "& 0377") will
+abort the automatic bisect process.
+
+You may often find that during bisect you want to have near-constant
+tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or
+"revision that does not have this commit needs this patch applied to
+work around other problem this bisection is not interested in")
+applied to the revision being tested.
+
+To cope with such a situation, after the inner git-bisect finds the
+next revision to test, with the "run" script, you can apply that tweak
+before compiling, run the real test, and after the test decides if the
+revision (possibly with the needed tweaks) passed the test, rewind the
+tree to the pristine state.  Finally the "run" script can exit with
+the status of the real test to let "git bisect run" command loop to
+know the outcome.
 
 Author
 ------