kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

Documentation/bisect: revise overall content 

Thoroughly revise the "git bisect" manpage, including:

* Beef up the "Description" section.

* Make the first long example less specific to kernel development.

* De-emphasize implementation details in a couple of places.

* Add "(roughly N steps)" in the places where example output is shown.

* Properly markup code within the prose.

* Lots of wordsmithing.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
maint
Michael Haggerty 2015-06-26 22:22:46 +02:00 committed by Junio C Hamano
parent c9493973a5
commit 2df5a846d0
1 changed files with 68 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
Documentation/git-bisect.txt
View File

@ -3,7 +3,7 @@ git-bisect(1)


NAME NAME
---- ----
git-bisect - Find by binary search the change that introduced a bug git-bisect - Use binary search to find the commit that introduced a bug




SYNOPSIS SYNOPSIS
@ -16,7 +16,6 @@ DESCRIPTION
The command takes various subcommands, and different options depending The command takes various subcommands, and different options depending
on the subcommand: on the subcommand:


git bisect help
git bisect start [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] git bisect start [--no-checkout] [<bad> [<good>...]] [--] [<paths>...]
git bisect bad [<rev>] git bisect bad [<rev>]
git bisect good [<rev>...] git bisect good [<rev>...]
@ -26,58 +25,71 @@ on the subcommand:
git bisect replay <logfile> git bisect replay <logfile>
git bisect log git bisect log
git bisect run <cmd>... git bisect run <cmd>...
git bisect help


This command uses 'git rev-list --bisect' to help drive the This command uses a binary search algorithm to find which commit in
binary search process to find which change introduced a bug, given an your project's history introduced a bug. You use it by first telling
old "good" commit object name and a later "bad" commit object name. it a "bad" commit that is known to contain the bug, and a "good"
commit that is known to be before the bug was introduced. Then `git
bisect` picks a commit between those two endpoints and asks you
whether the selected commit is "good" or "bad". It continues narrowing
down the range until it finds the exact commit that introduced the
change.


Basic bisect commands: start, bad, good Basic bisect commands: start, bad, good
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Using the Linux kernel tree as an example, basic use of the bisect As an example, suppose you are trying to find the commit that broke a
command is as follows: feature that was known to work in version `v2.6.13-rc2` of your
project. You start a bisect session as follows:


------------------------------------------------ ------------------------------------------------
$ git bisect start $ git bisect start
$ git bisect bad # Current version is bad $ git bisect bad # Current version is bad
$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 is known to be good
# tested that was good
------------------------------------------------ ------------------------------------------------


When you have specified at least one bad and one good version, the Once you have specified at least one bad and one good commit, `git
command bisects the revision tree and outputs something similar to bisect` selects a commit in the middle of that range of history,
the following: checks it out, and outputs something similar to the following:


------------------------------------------------ ------------------------------------------------
Bisecting: 675 revisions left to test after this Bisecting: 675 revisions left to test after this (roughly 10 steps)
------------------------------------------------ ------------------------------------------------


The state in the middle of the set of revisions is then checked out. You should now compile the checked-out version and test it. If that
You would now compile that kernel and boot it. If the booted kernel version works correctly, type
works correctly, you would then issue the following command:


------------------------------------------------ ------------------------------------------------
$ git bisect good # this one is good $ git bisect good
------------------------------------------------ ------------------------------------------------


The output of this command would be something similar to the following: If that version is broken, type


------------------------------------------------ ------------------------------------------------
Bisecting: 337 revisions left to test after this $ git bisect bad
------------------------------------------------ ------------------------------------------------


You keep repeating this process, compiling the tree, testing it, and Then `git bisect` will respond with something like
depending on whether it is good or bad issuing the command "git bisect good"
or "git bisect bad" to ask for the next bisection. ------------------------------------------------
Bisecting: 337 revisions left to test after this (roughly 9 steps)
------------------------------------------------

Keep repeating the process: compile the tree, test it, and depending
on whether it is good or bad run `git bisect good` or `git bisect bad`
to ask for the next commit that needs testing.

Eventually there will be no more revisions left to inspect, and the
command will print out a description of the first bad commit. The
reference `refs/bisect/bad` will be left pointing at that commit.


Eventually there will be no more revisions left to bisect, and you
will have been left with the first bad kernel revision in "refs/bisect/bad".


Bisect reset Bisect reset
~~~~~~~~~~~~ ~~~~~~~~~~~~


After a bisect session, to clean up the bisection state and return to After a bisect session, to clean up the bisection state and return to
the original HEAD (i.e., to quit bisecting), issue the following command: the original HEAD, issue the following command:


------------------------------------------------ ------------------------------------------------
$ git bisect reset $ git bisect reset
@ -94,9 +106,10 @@ instead:
$ git bisect reset <commit> $ git bisect reset <commit>
------------------------------------------------ ------------------------------------------------


For example, `git bisect reset HEAD` will leave you on the current For example, `git bisect reset bisect/bad` will check out the first
bisection commit and avoid switching commits at all, while `git bisect bad revision, while `git bisect reset HEAD` will leave you on the
reset bisect/bad` will check out the first bad revision. current bisection commit and avoid switching commits at all.



Bisect visualize Bisect visualize
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
@ -141,17 +154,17 @@ $ git bisect replay that-file
Avoiding testing a commit Avoiding testing a commit
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~


If, in the middle of a bisect session, you know that the next suggested If, in the middle of a bisect session, you know that the suggested
revision is not a good one to test (e.g. the change the commit revision is not a good one to test (e.g. it fails to build and you
introduces is known not to work in your environment and you know it know that the failure does not have anything to do with the bug you
does not have anything to do with the bug you are chasing), you may are chasing), you can manually select a nearby commit and test that
want to find a nearby commit and try that instead. one instead.


For example: For example:


------------ ------------
$ git bisect good/bad # previous round was good or bad. $ git bisect good/bad # previous round was good or bad.
Bisecting: 337 revisions left to test after this Bisecting: 337 revisions left to test after this (roughly 9 steps)
$ git bisect visualize # oops, that is uninteresting. $ git bisect visualize # oops, that is uninteresting.
$ git reset --hard HEAD~3 # try 3 revisions before what $ git reset --hard HEAD~3 # try 3 revisions before what
# was suggested # was suggested
@ -163,18 +176,19 @@ the revision as good or bad in the usual manner.
Bisect skip Bisect skip
~~~~~~~~~~~~ ~~~~~~~~~~~~


Instead of choosing by yourself a nearby commit, you can ask Git Instead of choosing a nearby commit by yourself, you can ask Git to do
to do it for you by issuing the command: it for you by issuing the command:


------------ ------------
$ git bisect skip # Current version cannot be tested $ git bisect skip # Current version cannot be tested
------------ ------------


But Git may eventually be unable to tell the first bad commit among However, if you skip a commit adjacent to the one you are looking for,
a bad commit and one or more skipped commits. Git will be unable to tell exactly which of those commits was the
first bad one.


You can even skip a range of commits, instead of just one commit, You can also skip a range of commits, instead of just one commit,
using the "'<commit1>'..'<commit2>'" notation. For example: using range notation. For example:


------------ ------------
$ git bisect skip v2.5..v2.6 $ git bisect skip v2.5..v2.6
@ -190,8 +204,8 @@ would issue the command:
$ git bisect skip v2.5 v2.5..v2.6 $ git bisect skip v2.5 v2.5..v2.6
------------ ------------


This tells the bisect process that the commits between `v2.5` included This tells the bisect process that the commits between `v2.5` and
and `v2.6` included should be skipped. `v2.6` (inclusive) should be skipped.




Cutting down bisection by giving more parameters to bisect start Cutting down bisection by giving more parameters to bisect start
@ -225,14 +239,14 @@ or bad, you can bisect by issuing the command:
$ git bisect run my_script arguments $ git bisect run my_script arguments
------------ ------------


Note that the script (`my_script` in the above example) should Note that the script (`my_script` in the above example) should exit
exit with code 0 if the current source code is good, and exit with a with code 0 if the current source code is good/old, and exit with a
code between 1 and 127 (inclusive), except 125, if the current code between 1 and 127 (inclusive), except 125, if the current source
source code is bad. code is bad/new.


Any other exit code will abort the bisect process. It should be noted Any other exit code will abort the bisect process. It should be noted
that a program that terminates via "exit(-1)" leaves $? = 255, (see the that a program that terminates via `exit(-1)` leaves $? = 255, (see the
exit(3) manual page), as the value is chopped with "& 0377". exit(3) manual page), as the value is chopped with `& 0377`.


The special exit code 125 should be used when the current source code The special exit code 125 should be used when the current source code
cannot be tested. If the script exits with this code, the current cannot be tested. If the script exits with this code, the current
@ -241,7 +255,7 @@ as the highest sensible value to use for this purpose, because 126 and 127
are used by POSIX shells to signal specific error status (127 is for are used by POSIX shells to signal specific error status (127 is for
command not found, 126 is for command found but not executable---these command not found, 126 is for command found but not executable---these
details do not matter, as they are normal errors in the script, as far as details do not matter, as they are normal errors in the script, as far as
"bisect run" is concerned). `bisect run` is concerned).


You may often find that during a bisect session you want to have You may often find that during a bisect session you want to have
temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a
@ -254,7 +268,7 @@ next revision to test, the script can apply the patch
before compiling, run the real test, and afterwards decide if the before compiling, run the real test, and afterwards decide if the
revision (possibly with the needed patch) passed the test and then revision (possibly with the needed patch) passed the test and then
rewind the tree to the pristine state. Finally the script should exit rewind the tree to the pristine state. Finally the script should exit
with the status of the real test to let the "git bisect run" command loop with the status of the real test to let the `git bisect run` command loop
determine the eventual outcome of the bisect session. determine the eventual outcome of the bisect session.


OPTIONS OPTIONS
@ -301,12 +315,12 @@ $ git bisect run ~/test.sh
$ git bisect reset # quit the bisect session $ git bisect reset # quit the bisect session
------------ ------------
+ +
Here we use a "test.sh" custom script. In this script, if "make" Here we use a `test.sh` custom script. In this script, if `make`
fails, we skip the current commit. fails, we skip the current commit.
"check_test_case.sh" should "exit 0" if the test case passes, `check_test_case.sh` should `exit 0` if the test case passes,
and "exit 1" otherwise. and `exit 1` otherwise.
+ +
It is safer if both "test.sh" and "check_test_case.sh" are It is safer if both `test.sh` and `check_test_case.sh` are
outside the repository to prevent interactions between the bisect, outside the repository to prevent interactions between the bisect,
make and test processes and the scripts. make and test processes and the scripts.