git-bisect.html - external/gitster/git-htmldocs - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
  "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 <meta name="generator" content="AsciiDoc 7.0.1" />
 <style type="text/css">
 /* Debug borders */
 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
 /*
  border: 1px solid red;
 */
 }

 body {
  margin: 1em 5% 1em 5%;
 }

 a { color: blue; }
 a:visited { color: fuchsia; }

 em {
  font-style: italic;
 }

 strong {
  font-weight: bold;
 }

 tt {
  color: navy;
 }

 h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
 }

 h1 {
  border-bottom: 2px solid silver;
 }
 h2 {
  border-bottom: 2px solid silver;
  padding-top: 0.5em;
 }

 div.sectionbody {
  font-family: serif;
  margin-left: 0;
 }

 hr {
  border: 1px solid silver;
 }

 p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
 }

 pre {
  padding: 0;
  margin: 0;
 }

 span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.2em;
 }
 span#email {
 }
 span#revision {
  font-family: sans-serif;
 }

 div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
 }
 div#footer-text {
  float: left;
  padding-bottom: 0.5em;
 }
 div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
 }

 div#preamble,
 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 div.admonitionblock {
  margin-right: 10%;
  margin-top: 1.5em;
  margin-bottom: 1.5em;
 }
 div.admonitionblock {
  margin-top: 2.5em;
  margin-bottom: 2.5em;
 }

 div.content { /* Block element content. */
  padding: 0;
 }

 /* Block element titles. */
 div.title, caption.title {
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
 }
 div.title + * {
  margin-top: 0;
 }

 td div.title:first-child {
  margin-top: 0.0em;
 }
 div.content div.title:first-child {
  margin-top: 0.0em;
 }
 div.content + div.title {
  margin-top: 0.0em;
 }

 div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
 }

 div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
 }

 div.quoteblock > div.content {
  padding-left: 2.0em;
 }
 div.quoteblock .attribution {
  text-align: right;
 }

 div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
 }
 div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 2px solid silver;
 }

 div.exampleblock > div.content {
  border-left: 2px solid silver;
  padding: 0.5em;
 }

 div.verseblock div.content {
  white-space: pre;
 }

 div.imageblock div.content { padding-left: 0; }
 div.imageblock img { border: 1px solid silver; }
 span.image img { border-style: none; }

 dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: italic;
 }
 dd > *:first-child {
  margin-top: 0;
 }

 ul, ol {
  list-style-position: outside;
 }
 ol.olist2 {
  list-style-type: lower-alpha;
 }

 div.tableblock > table {
  border-color: #527bbd;
  border-width: 3px;
 }
 thead {
  font-family: sans-serif;
  font-weight: bold;
 }
 tfoot {
  font-weight: bold;
 }

 div.hlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 td.hlist1 {
  vertical-align: top;
  font-style: italic;
  padding-right: 0.8em;
 }
 td.hlist2 {
  vertical-align: top;
 }

 @media print {
  div#footer-badges { display: none; }
 }
 include::./stylesheets/xhtml11-manpage.css[]
 /* Workarounds for IE6's broken and incomplete CSS2. */

 div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
 }
 div.sidebar-title, div.image-title {
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
 }

 div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
 }

 div.quoteblock-content {
  padding-left: 2.0em;
 }

 div.exampleblock-content {
  border-left: 2px solid silver;
  padding-left: 0.5em;
 }
 </style>
 <title>git-bisect(1)</title>
 </head>
 <body>
 <div id="header">
 <h1>
 git-bisect(1) Manual Page
 </h1>
 <h2>NAME</h2>
 <div class="sectionbody">
 <p>git-bisect -
  Find the change that introduced a bug
 </p>
 </div>
 </div>
 <h2>SYNOPSIS</h2>
 <div class="sectionbody">
 <p><em>git bisect</em> &lt;subcommand&gt; &lt;options&gt;</p>
 </div>
 <h2>DESCRIPTION</h2>
 <div class="sectionbody">
 <p>The command takes various subcommands, and different options
 depending on the subcommand:</p>
 <div class="literalblock">
 <div class="content">
 <pre><tt>git bisect start [&lt;paths&gt;...]
 git bisect bad &lt;rev&gt;
 git bisect good &lt;rev&gt;
 git bisect reset [&lt;branch&gt;]
 git bisect visualize
 git bisect replay &lt;logfile&gt;
 git bisect log</tt></pre>
 </div></div>
 <p>This command uses <em>git-rev-list --bisect</em> 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
 object name.</p>
 <p>The way you use it is:</p>
 <div class="listingblock">
 <div class="content">
 <pre><tt>$ 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</tt></pre>
 </div></div>
 <p>When you give at least one bad and one good versions, it will
 bisect the revision tree and say something like:</p>
 <div class="listingblock">
 <div class="content">
 <pre><tt>Bisecting: 675 revisions left to test after this</tt></pre>
 </div></div>
 <p>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</p>
 <div class="listingblock">
 <div class="content">
 <pre><tt>$ git bisect good # this one is good</tt></pre>
 </div></div>
 <p>which will now say</p>
 <div class="listingblock">
 <div class="content">
 <pre><tt>Bisecting: 337 revisions left to test after this</tt></pre>
 </div></div>
 <p>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.</p>
 <p>Until you have no more left, and you'll have been left with the first bad
 kernel rev in "refs/bisect/bad".</p>
 <p>Oh, and then after you want to reset to the original head, do a</p>
 <div class="listingblock">
 <div class="content">
 <pre><tt>$ git bisect reset</tt></pre>
 </div></div>
 <p>to get back to the master branch, instead of being in one of the bisection
 branches ("git bisect start" will do that for you too, actually: it will
 reset the bisection state, and before it does that it checks that you're
 not using some old bisection branch).</p>
 <p>During the bisection process, you can say</p>
 <div class="listingblock">
 <div class="content">
 <pre><tt>$ git bisect visualize</tt></pre>
 </div></div>
 <p>to see the currently remaining suspects in <tt>gitk</tt>.</p>
 <p>The good/bad input is logged, and <tt>git bisect
 log</tt> shows what you have done so far. You can truncate its
 output somewhere and save it in a file, and run</p>
 <div class="listingblock">
 <div class="content">
 <pre><tt>$ git bisect replay that-file</tt></pre>
 </div></div>
 <p>if you find later you made a mistake telling good/bad about a
 revision.</p>
 <p>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:</p>
 <div class="listingblock">
 <div class="content">
 <pre><tt>$ 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</tt></pre>
 </div></div>
 <p>Then compile and test the one you chose to try. After that,
 tell bisect what the result was as usual.</p>
 <p>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 <tt>bisect start</tt>,
 like this:</p>
 <div class="listingblock">
 <div class="content">
 <pre><tt>$ git bisect start arch/i386 include/asm-i386</tt></pre>
 </div></div>
 </div>
 <h2>Author</h2>
 <div class="sectionbody">
 <p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt;</p>
 </div>
 <h2>Documentation</h2>
 <div class="sectionbody">
 <p>Documentation by Junio C Hamano and the git-list &lt;git@vger.kernel.org&gt;.</p>
 </div>
 <h2>GIT</h2>
 <div class="sectionbody">
 <p>Part of the <a href="git.html">git(7)</a> suite</p>
 </div>
 <div id="footer">
 <div id="footer-text">
 Last updated 27-Dec-2005 00:15:48 PDT
 </div>
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<meta name="generator" content="AsciiDoc 7.0.1" />
	<style type="text/css">
	/* Debug borders */
	p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
	/*
	border: 1px solid red;
	*/
	}

	body {
	margin: 1em 5% 1em 5%;
	}

	a { color: blue; }
	a:visited { color: fuchsia; }

	em {
	font-style: italic;
	}

	strong {
	font-weight: bold;
	}

	tt {
	color: navy;
	}

	h1, h2, h3, h4, h5, h6 {
	color: #527bbd;
	font-family: sans-serif;
	margin-top: 1.2em;
	margin-bottom: 0.5em;
	line-height: 1.3;
	}

	h1 {
	border-bottom: 2px solid silver;
	}
	h2 {
	border-bottom: 2px solid silver;
	padding-top: 0.5em;
	}

	div.sectionbody {
	font-family: serif;
	margin-left: 0;
	}

	hr {
	border: 1px solid silver;
	}

	p {
	margin-top: 0.5em;
	margin-bottom: 0.5em;
	}

	pre {
	padding: 0;
	margin: 0;
	}

	span#author {
	color: #527bbd;
	font-family: sans-serif;
	font-weight: bold;
	font-size: 1.2em;
	}
	span#email {
	}
	span#revision {
	font-family: sans-serif;
	}

	div#footer {
	font-family: sans-serif;
	font-size: small;
	border-top: 2px solid silver;
	padding-top: 0.5em;
	margin-top: 4.0em;
	}
	div#footer-text {
	float: left;
	padding-bottom: 0.5em;
	}
	div#footer-badges {
	float: right;
	padding-bottom: 0.5em;
	}

	div#preamble,
	div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
	div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
	div.admonitionblock {
	margin-right: 10%;
	margin-top: 1.5em;
	margin-bottom: 1.5em;
	}
	div.admonitionblock {
	margin-top: 2.5em;
	margin-bottom: 2.5em;
	}

	div.content { /* Block element content. */
	padding: 0;
	}

	/* Block element titles. */
	div.title, caption.title {
	font-family: sans-serif;
	font-weight: bold;
	text-align: left;
	margin-top: 1.0em;
	margin-bottom: 0.5em;
	}
	div.title + * {
	margin-top: 0;
	}

	td div.title:first-child {
	margin-top: 0.0em;
	}
	div.content div.title:first-child {
	margin-top: 0.0em;
	}
	div.content + div.title {
	margin-top: 0.0em;
	}

	div.sidebarblock > div.content {
	background: #ffffee;
	border: 1px solid silver;
	padding: 0.5em;
	}

	div.listingblock > div.content {
	border: 1px solid silver;
	background: #f4f4f4;
	padding: 0.5em;
	}

	div.quoteblock > div.content {
	padding-left: 2.0em;
	}
	div.quoteblock .attribution {
	text-align: right;
	}

	div.admonitionblock .icon {
	vertical-align: top;
	font-size: 1.1em;
	font-weight: bold;
	text-decoration: underline;
	color: #527bbd;
	padding-right: 0.5em;
	}
	div.admonitionblock td.content {
	padding-left: 0.5em;
	border-left: 2px solid silver;
	}

	div.exampleblock > div.content {
	border-left: 2px solid silver;
	padding: 0.5em;
	}

	div.verseblock div.content {
	white-space: pre;
	}

	div.imageblock div.content { padding-left: 0; }
	div.imageblock img { border: 1px solid silver; }
	span.image img { border-style: none; }

	dl {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	dt {
	margin-top: 0.5em;
	margin-bottom: 0;
	font-style: italic;
	}
	dd > *:first-child {
	margin-top: 0;
	}

	ul, ol {
	list-style-position: outside;
	}
	ol.olist2 {
	list-style-type: lower-alpha;
	}

	div.tableblock > table {
	border-color: #527bbd;
	border-width: 3px;
	}
	thead {
	font-family: sans-serif;
	font-weight: bold;
	}
	tfoot {
	font-weight: bold;
	}

	div.hlist {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	td.hlist1 {
	vertical-align: top;
	font-style: italic;
	padding-right: 0.8em;
	}
	td.hlist2 {
	vertical-align: top;
	}

	@media print {
	div#footer-badges { display: none; }
	}
	include::./stylesheets/xhtml11-manpage.css[]
	/* Workarounds for IE6's broken and incomplete CSS2. */

	div.sidebar-content {
	background: #ffffee;
	border: 1px solid silver;
	padding: 0.5em;
	}
	div.sidebar-title, div.image-title {
	font-family: sans-serif;
	font-weight: bold;
	margin-top: 0.0em;
	margin-bottom: 0.5em;
	}

	div.listingblock div.content {
	border: 1px solid silver;
	background: #f4f4f4;
	padding: 0.5em;
	}

	div.quoteblock-content {
	padding-left: 2.0em;
	}

	div.exampleblock-content {
	border-left: 2px solid silver;
	padding-left: 0.5em;
	}
	</style>
	<title>git-bisect(1)</title>
	</head>
	<body>
	<div id="header">
	<h1>
	git-bisect(1) Manual Page
	</h1>
	<h2>NAME</h2>
	<div class="sectionbody">
	<p>git-bisect -
	Find the change that introduced a bug
	</p>
	</div>
	</div>
	<h2>SYNOPSIS</h2>
	<div class="sectionbody">
	<p><em>git bisect</em> <subcommand> <options></p>
	</div>
	<h2>DESCRIPTION</h2>
	<div class="sectionbody">
	<p>The command takes various subcommands, and different options
	depending on the subcommand:</p>
	<div class="literalblock">
	<div class="content">
	<pre><tt>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</tt></pre>
	</div></div>
	<p>This command uses <em>git-rev-list --bisect</em> 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
	object name.</p>
	<p>The way you use it is:</p>
	<div class="listingblock">
	<div class="content">
	<pre><tt>$ 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</tt></pre>
	</div></div>
	<p>When you give at least one bad and one good versions, it will
	bisect the revision tree and say something like:</p>
	<div class="listingblock">
	<div class="content">
	<pre><tt>Bisecting: 675 revisions left to test after this</tt></pre>
	</div></div>
	<p>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</p>
	<div class="listingblock">
	<div class="content">
	<pre><tt>$ git bisect good # this one is good</tt></pre>
	</div></div>
	<p>which will now say</p>
	<div class="listingblock">
	<div class="content">
	<pre><tt>Bisecting: 337 revisions left to test after this</tt></pre>
	</div></div>
	<p>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.</p>
	<p>Until you have no more left, and you'll have been left with the first bad
	kernel rev in "refs/bisect/bad".</p>
	<p>Oh, and then after you want to reset to the original head, do a</p>
	<div class="listingblock">
	<div class="content">
	<pre><tt>$ git bisect reset</tt></pre>
	</div></div>
	<p>to get back to the master branch, instead of being in one of the bisection
	branches ("git bisect start" will do that for you too, actually: it will
	reset the bisection state, and before it does that it checks that you're
	not using some old bisection branch).</p>
	<p>During the bisection process, you can say</p>
	<div class="listingblock">
	<div class="content">
	<pre><tt>$ git bisect visualize</tt></pre>
	</div></div>
	<p>to see the currently remaining suspects in <tt>gitk</tt>.</p>
	<p>The good/bad input is logged, and <tt>git bisect
	log</tt> shows what you have done so far. You can truncate its
	output somewhere and save it in a file, and run</p>
	<div class="listingblock">
	<div class="content">
	<pre><tt>$ git bisect replay that-file</tt></pre>
	</div></div>
	<p>if you find later you made a mistake telling good/bad about a
	revision.</p>
	<p>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:</p>
	<div class="listingblock">
	<div class="content">
	<pre><tt>$ 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</tt></pre>
	</div></div>
	<p>Then compile and test the one you chose to try. After that,
	tell bisect what the result was as usual.</p>
	<p>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 <tt>bisect start</tt>,
	like this:</p>
	<div class="listingblock">
	<div class="content">
	<pre><tt>$ git bisect start arch/i386 include/asm-i386</tt></pre>
	</div></div>
	</div>
	<h2>Author</h2>
	<div class="sectionbody">
	<p>Written by Linus Torvalds <torvalds@osdl.org></p>
	</div>
	<h2>Documentation</h2>
	<div class="sectionbody">
	<p>Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.</p>
	</div>
	<h2>GIT</h2>
	<div class="sectionbody">
	<p>Part of the <a href="git.html">git(7)</a> suite</p>
	</div>
	<div id="footer">
	<div id="footer-text">
	Last updated 27-Dec-2005 00:15:48 PDT
	</div>
	</div>
	</body>
	</html>