* dm/maint-docco:
Documentation: Remove spurious uses of "you" in git-bisect.txt.
Documentation: minor grammatical fix in git-check-ref-format.txt
Documentation: minor grammatical fixes in git-check-attr.txt
Documentation: minor grammatical fixes in git-cat-file.txt
Documentation: minor grammatical fixes and rewording in git-bundle.txt
Documentation: remove some uses of the passive voice in git-bisect.txt
Documentation: reword example text in git-bisect.txt.
Documentation: reworded the "Description" section of git-bisect.txt.
Documentation: minor grammatical fixes in git-branch.txt.
Documentation: minor grammatical fixes in git-blame.txt.
Documentation: reword the "Description" section of git-bisect.txt.
Documentation: minor grammatical fixes in git-archive.txt.
git-bisect - Find the change that introduced a bug by binary search
git-bisect - Find by binary search the change that introduced a bug
SYNOPSIS
@ -39,7 +39,8 @@ help" or "git bisect -h" to get a long usage description.
@@ -39,7 +39,8 @@ help" or "git bisect -h" to get a long usage description.
Basic bisect commands: start, bad, good
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The way you use it is:
Using the Linux kernel tree as an example, basic use of the bisect
command is as follows:
------------------------------------------------
$ git bisect start
@ -48,61 +49,63 @@ $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version
@@ -48,61 +49,63 @@ $ 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 bisect
the revision tree and say something like:
When you have specified at least one bad and one good version, the
command bisects the revision tree and outputs something similar to
the following:
------------------------------------------------
Bisecting: 675 revisions left to test after this
------------------------------------------------
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
The state in the middle of the set of revisions is then checked out.
You would now compile that kernel and boot it. If the booted kernel
works correctly, you would then issue the following command:
------------------------------------------------
$ git bisect good # this one is good
------------------------------------------------
which will now say
The output of this command would be something similar to the following:
------------------------------------------------
Bisecting: 337 revisions left to test after this
------------------------------------------------
and you continue along, compiling that one, testing it, and depending
on whether it is good or bad, you say "git bisect good" or "git bisect
bad", and ask for the next bisection.
You keep repeating this process, compiling the tree, testing it, and
depending on whether it is good or bad issuing the command "git bisect good"
or "git bisect bad" to ask for the next bisection.
Until you have no more left, and you'll have been left with the first
bad kernel rev in "refs/bisect/bad".
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
~~~~~~~~~~~~
Oh, and then after you want to reset to the original head, do a
To return to the original head after a bisect session, issue the
following command:
------------------------------------------------
$ git bisect reset
------------------------------------------------
to get back to the original branch, instead of being on the bisection
commit ("git bisect start" will do that for you too, actually: it will
reset the bisection state).
This resets the tree to the original branch instead of being on the
bisection commit ("git bisect start" will also do that, as it resets
the bisection state).
Bisect visualize
~~~~~~~~~~~~~~~~
During the bisection process, you can say
To see the currently remaining suspects in 'gitk', issue the following
command during the bisection process:
------------
$ git bisect visualize
------------
to see the currently remaining suspects in 'gitk'. `visualize` is a bit
too long to type and `view` is provided as a synonym.
`view` may also be used as a synonym for `visualize`.
If 'DISPLAY' environment variable is not set, 'git log' is used
instead. You can even give command line options such as `-p` and
If the 'DISPLAY' environment variable is not set, 'git log' is used
instead. You can also give command line options such as `-p` and
After having marked revisions as good or bad, issue the following
command to show what has been done so far:
------------
$ git bisect log
------------
shows what you have done so far. You can truncate its output somewhere
and save it in a file, and run
If you discover that you made a mistake in specifying the status of a
revision, you can save the output of this command to a file, edit it to
remove the incorrect entries, and then issue the following commands to
return to a corrected state:
------------
$ git bisect reset
$ git bisect replay that-file
------------
if you find later you made a mistake telling good/bad about a
revision.
Avoiding to test a commit
Avoiding testing a commit
~~~~~~~~~~~~~~~~~~~~~~~~~
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
If, in the middle of a bisect session, you know that the next suggested
revision 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.
want to find a nearby commit and try that instead.
It goes something like this:
For example:
------------
$ git bisect good/bad # previous round was good/bad.
$ git bisect good/bad # previous round was good or 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
$ git reset --hard HEAD~3 # try 3 revisions before what
# was suggested
------------
Then compile and test the one you chose to try. After that, tell
bisect what the result was as usual.
Then compile and test the chosen revision, and afterwards mark
the revision as good or bad in the usual manner.
Bisect skip
~~~~~~~~~~~~
Instead of choosing by yourself a nearby commit, you may just want git
to do it for you using:
Instead of choosing by yourself a nearby commit, you can ask git
to do it for you by issuing the command:
------------
$ git bisect skip # Current version cannot be tested
------------
But computing the commit to test may be slower afterwards and git may
eventually not be able to tell the first bad among a bad and one or
more "skip"ped commits.
eventually not be able to tell the first bad commit among a bad commit
and one or more skipped commits.
You can even skip a range of commits, instead of just one commit,
using the "'<commit1>'..'<commit2>'" notation. For example:
@ -171,33 +175,34 @@ using the "'<commit1>'..'<commit2>'" notation. For example:
@@ -171,33 +175,34 @@ using the "'<commit1>'..'<commit2>'" notation. For example:
$ git bisect skip v2.5..v2.6
------------
would mean that no commit between `v2.5` excluded and `v2.6` included
can be tested.
This tells the bisect process that no commit after `v2.5`, up to and
including `v2.6`, should be tested.
Note that if you want to also skip the first commit of a range you can
use something like:
Note that if you also want to skip the first commit of the range you
would issue the command:
------------
$ git bisect skip v2.5 v2.5..v2.6
------------
and the commit pointed to by `v2.5` will be skipped too.
This tells the bisect process that the commits between `v2.5` included
and `v2.6` included should be skipped.
Cutting down bisection by giving more parameters to bisect start
lines between files (see `-C`) and lines moved within a
file (see `-M`). The first number listed is the score.
This is the number of alphanumeric characters detected
to be moved between or within files. This must be above
as having been moved between or within files. This must be above
a certain threshold for 'git-blame' to consider those lines
of code to have been moved.
-f::
--show-name::
Show filename in the original commit. By default
filename is shown if there is any line that came from a
file with different name, due to rename detection.
Show the filename in the original commit. By default
the filename is shown if there is any line that came from a
file with a different name, due to rename detection.
-n::
--show-number::
Show line number in the original commit (Default: off).
Show the line number in the original commit (Default: off).
-s::
Suppress author name and timestamp from the output.
Suppress the author name and timestamp from the output.
-w::
Ignore whitespace when comparing parent's version and
child's to find where the lines came from.
Ignore whitespace when comparing the parent's version and
the child's to find where the lines came from.
THE PORCELAIN FORMAT
@ -79,17 +79,17 @@ header at the minimum has the first line which has:
@@ -79,17 +79,17 @@ header at the minimum has the first line which has:
- 40-byte SHA-1 of the commit the line is attributed to;
- the line number of the line in the original file;
- the line number of the line in the final file;
- on a line that starts a group of line from a different
- on a line that starts a group of lines from a different
commit than the previous one, the number of lines in this
group. On subsequent lines this field is absent.
This header line is followed by the following information
at least once for each commit:
- author name ("author"), email ("author-mail"), time
- the author name ("author"), email ("author-mail"), time
("author-time"), and timezone ("author-tz"); similarly
for committer.
- filename in the commit the line is attributed to.
- the filename in the commit that the line is attributed to.
- the first line of the commit log message ("summary").
The contents of the actual line is output after the above
@ -100,23 +100,23 @@ header elements later.
@@ -100,23 +100,23 @@ header elements later.
SPECIFYING RANGES
-----------------
Unlike 'git-blame' and 'git-annotate' in older git, the extent
of annotation can be limited to both line ranges and revision
Unlike 'git-blame' and 'git-annotate' in older versions of git, the extent
of the annotation can be limited to both line ranges and revision
ranges. When you are interested in finding the origin for
ll. 40-60 for file `foo`, you can use `-L` option like these
lines 40-60 for file `foo`, you can use the `-L` option like so
(they mean the same thing -- both ask for 21 lines starting at
line 40):
git blame -L 40,60 foo
git blame -L 40,+21 foo
Also you can use regular expression to specify the line range.
Also you can use a regular expression to specify the line range:
git blame -L '/^sub hello {/,/^}$/' foo
would limit the annotation to the body of `hello` subroutine.
which limits the annotation to the body of the `hello` subroutine.
When you are not interested in changes older than the version
When you are not interested in changes older than version
v2.6.18, or changes older than 3 weeks, you can use revision
range specifiers similar to 'git-rev-list':
@ -129,7 +129,7 @@ commit v2.6.18 or the most recent commit that is more than 3
@@ -129,7 +129,7 @@ commit v2.6.18 or the most recent commit that is more than 3
weeks old in the above example) are blamed for that range
boundary commit.
A particularly useful way is to see if an added file have lines
A particularly useful way is to see if an added file has lines
created by copy-and-paste from existing files. Sometimes this
indicates that the developer was being sloppy and did not
refactor the code properly. You can first find the commit that
Junio C Hamano
16 years ago