Google Git
Sign in
chromium / external / gitster / git-htmldocs / dd4c178beaaa13be1f0211908f194c136b341973 / . / git-bisect.html
blob: 09845e256be5aa4cc46920aa1a900278d1da5d8e [file] [log] [blame]
Junio C Hamano96153bf2018-04-25 08:25:34[diff] [blame]1<?xml version="1.0" encoding="UTF-8"?>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
3 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
4<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
5<head>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]6<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
Junio C Hamanoeaa95f72020-04-14 17:39:35[diff] [blame]7<meta name="generator" content="AsciiDoc 9.0.0rc1" />
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]8<title>git-bisect(1)</title>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]9<style type="text/css">
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]10/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
11
12/* Default font. */
13body {
14 font-family: Georgia,serif;
15}
16
17/* Title font. */
18h1, h2, h3, h4, h5, h6,
19div.title, caption.title,
20thead, p.table.header,
21#toctitle,
22#author, #revnumber, #revdate, #revremark,
23#footer {
24 font-family: Arial,Helvetica,sans-serif;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]25}
26
27body {
28 margin: 1em 5% 1em 5%;
29}
30
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]31a {
32 color: blue;
33 text-decoration: underline;
34}
35a:visited {
36 color: fuchsia;
37}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]38
39em {
40 font-style: italic;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]41 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]42}
43
44strong {
45 font-weight: bold;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]46 color: #083194;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]47}
48
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]49h1, h2, h3, h4, h5, h6 {
50 color: #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]51 margin-top: 1.2em;
52 margin-bottom: 0.5em;
53 line-height: 1.3;
54}
55
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]56h1, h2, h3 {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]57 border-bottom: 2px solid silver;
58}
59h2 {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]60 padding-top: 0.5em;
61}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]62h3 {
63 float: left;
64}
65h3 + * {
66 clear: left;
67}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]68h5 {
69 font-size: 1.0em;
70}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]71
72div.sectionbody {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]73 margin-left: 0;
74}
75
76hr {
77 border: 1px solid silver;
78}
79
80p {
81 margin-top: 0.5em;
82 margin-bottom: 0.5em;
83}
84
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]85ul, ol, li > p {
86 margin-top: 0;
87}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]88ul > li { color: #aaa; }
89ul > li > * { color: black; }
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]90
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]91.monospaced, code, pre {
92 font-family: "Courier New", Courier, monospace;
93 font-size: inherit;
94 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]95 padding: 0;
96 margin: 0;
97}
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]98pre {
99 white-space: pre-wrap;
100}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]101
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]102#author {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]103 color: #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]104 font-weight: bold;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]105 font-size: 1.1em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]106}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]107#email {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]108}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]109#revnumber, #revdate, #revremark {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]110}
111
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]112#footer {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]113 font-size: small;
114 border-top: 2px solid silver;
115 padding-top: 0.5em;
116 margin-top: 4.0em;
117}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]118#footer-text {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]119 float: left;
120 padding-bottom: 0.5em;
121}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]122#footer-badges {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]123 float: right;
124 padding-bottom: 0.5em;
125}
126
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]127#preamble {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]128 margin-top: 1.5em;
129 margin-bottom: 1.5em;
130}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]131div.imageblock, div.exampleblock, div.verseblock,
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]132div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
133div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]134 margin-top: 1.0em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]135 margin-bottom: 1.5em;
136}
137div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]138 margin-top: 2.0em;
139 margin-bottom: 2.0em;
140 margin-right: 10%;
141 color: #606060;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]142}
143
144div.content { /* Block element content. */
145 padding: 0;
146}
147
148/* Block element titles. */
149div.title, caption.title {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]150 color: #527bbd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]151 font-weight: bold;
152 text-align: left;
153 margin-top: 1.0em;
154 margin-bottom: 0.5em;
155}
156div.title + * {
157 margin-top: 0;
158}
159
160td div.title:first-child {
161 margin-top: 0.0em;
162}
163div.content div.title:first-child {
164 margin-top: 0.0em;
165}
166div.content + div.title {
167 margin-top: 0.0em;
168}
169
170div.sidebarblock > div.content {
171 background: #ffffee;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]172 border: 1px solid #dddddd;
173 border-left: 4px solid #f0f0f0;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]174 padding: 0.5em;
175}
176
177div.listingblock > div.content {
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]178 border: 1px solid #dddddd;
179 border-left: 5px solid #f0f0f0;
180 background: #f8f8f8;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]181 padding: 0.5em;
182}
183
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]184div.quoteblock, div.verseblock {
185 padding-left: 1.0em;
186 margin-left: 1.0em;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]187 margin-right: 10%;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]188 border-left: 5px solid #f0f0f0;
189 color: #888;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]190}
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]191
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]192div.quoteblock > div.attribution {
193 padding-top: 0.5em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]194 text-align: right;
195}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]196
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]197div.verseblock > pre.content {
198 font-family: inherit;
199 font-size: inherit;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]200}
201div.verseblock > div.attribution {
202 padding-top: 0.75em;
203 text-align: left;
204}
205/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]206div.verseblock + div.attribution {
207 text-align: left;
208}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]209
210div.admonitionblock .icon {
211 vertical-align: top;
212 font-size: 1.1em;
213 font-weight: bold;
214 text-decoration: underline;
215 color: #527bbd;
216 padding-right: 0.5em;
217}
218div.admonitionblock td.content {
219 padding-left: 0.5em;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]220 border-left: 3px solid #dddddd;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]221}
222
223div.exampleblock > div.content {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]224 border-left: 3px solid #dddddd;
225 padding-left: 0.5em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]226}
227
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]228div.imageblock div.content { padding-left: 0; }
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]229span.image img { border-style: none; vertical-align: text-bottom; }
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]230a.image:visited { color: white; }
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]231
232dl {
233 margin-top: 0.8em;
234 margin-bottom: 0.8em;
235}
236dt {
237 margin-top: 0.5em;
238 margin-bottom: 0;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]239 font-style: normal;
240 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]241}
242dd > *:first-child {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]243 margin-top: 0.1em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]244}
245
246ul, ol {
247 list-style-position: outside;
248}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]249ol.arabic {
250 list-style-type: decimal;
251}
252ol.loweralpha {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]253 list-style-type: lower-alpha;
254}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]255ol.upperalpha {
256 list-style-type: upper-alpha;
257}
258ol.lowerroman {
259 list-style-type: lower-roman;
260}
261ol.upperroman {
262 list-style-type: upper-roman;
263}
264
265div.compact ul, div.compact ol,
266div.compact p, div.compact p,
267div.compact div, div.compact div {
268 margin-top: 0.1em;
269 margin-bottom: 0.1em;
270}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]271
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]272tfoot {
273 font-weight: bold;
274}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]275td > div.verse {
276 white-space: pre;
277}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]278
279div.hdlist {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]280 margin-top: 0.8em;
281 margin-bottom: 0.8em;
282}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]283div.hdlist tr {
284 padding-bottom: 15px;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]285}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]286dt.hdlist1.strong, td.hdlist1.strong {
287 font-weight: bold;
288}
289td.hdlist1 {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]290 vertical-align: top;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]291 font-style: normal;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]292 padding-right: 0.8em;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]293 color: navy;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]294}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]295td.hdlist2 {
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]296 vertical-align: top;
297}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]298div.hdlist.compact tr {
299 margin: 0;
300 padding-bottom: 0;
301}
302
303.comment {
304 background: yellow;
305}
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]306
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]307.footnote, .footnoteref {
308 font-size: 0.8em;
309}
310
311span.footnote, span.footnoteref {
312 vertical-align: super;
313}
314
315#footnotes {
316 margin: 20px 0 20px 0;
317 padding: 7px 0 0 0;
318}
319
320#footnotes div.footnote {
321 margin: 0 0 5px 0;
322}
323
324#footnotes hr {
325 border: none;
326 border-top: 1px solid silver;
327 height: 1px;
328 text-align: left;
329 margin-left: 0;
330 width: 20%;
331 min-width: 100px;
332}
333
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]334div.colist td {
335 padding-right: 0.5em;
336 padding-bottom: 0.3em;
337 vertical-align: top;
338}
339div.colist td img {
340 margin-top: 0.3em;
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]341}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]342
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]343@media print {
344 #footer-badges { display: none; }
345}
346
347#toc {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]348 margin-bottom: 2.5em;
349}
350
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]351#toctitle {
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]352 color: #527bbd;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]353 font-size: 1.1em;
354 font-weight: bold;
355 margin-top: 1.0em;
356 margin-bottom: 0.1em;
357}
358
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]359div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]360 margin-top: 0;
361 margin-bottom: 0;
362}
363div.toclevel2 {
364 margin-left: 2em;
365 font-size: 0.9em;
366}
367div.toclevel3 {
368 margin-left: 4em;
369 font-size: 0.9em;
370}
371div.toclevel4 {
372 margin-left: 6em;
373 font-size: 0.9em;
374}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]375
376span.aqua { color: aqua; }
377span.black { color: black; }
378span.blue { color: blue; }
379span.fuchsia { color: fuchsia; }
380span.gray { color: gray; }
381span.green { color: green; }
382span.lime { color: lime; }
383span.maroon { color: maroon; }
384span.navy { color: navy; }
385span.olive { color: olive; }
386span.purple { color: purple; }
387span.red { color: red; }
388span.silver { color: silver; }
389span.teal { color: teal; }
390span.white { color: white; }
391span.yellow { color: yellow; }
392
393span.aqua-background { background: aqua; }
394span.black-background { background: black; }
395span.blue-background { background: blue; }
396span.fuchsia-background { background: fuchsia; }
397span.gray-background { background: gray; }
398span.green-background { background: green; }
399span.lime-background { background: lime; }
400span.maroon-background { background: maroon; }
401span.navy-background { background: navy; }
402span.olive-background { background: olive; }
403span.purple-background { background: purple; }
404span.red-background { background: red; }
405span.silver-background { background: silver; }
406span.teal-background { background: teal; }
407span.white-background { background: white; }
408span.yellow-background { background: yellow; }
409
410span.big { font-size: 2em; }
411span.small { font-size: 0.6em; }
412
413span.underline { text-decoration: underline; }
414span.overline { text-decoration: overline; }
415span.line-through { text-decoration: line-through; }
416
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]417div.unbreakable { page-break-inside: avoid; }
418
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]419
420/*
421 * xhtml11 specific
422 *
423 * */
424
425div.tableblock {
426 margin-top: 1.0em;
427 margin-bottom: 1.5em;
428}
429div.tableblock > table {
430 border: 3px solid #527bbd;
431}
432thead, p.table.header {
433 font-weight: bold;
434 color: #527bbd;
435}
436p.table {
437 margin-top: 0;
438}
Junio C Hamano725b0da2020-01-22 22:02:40[diff] [blame]439/* Because the table frame attribute is overridden by CSS in most browsers. */
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]440div.tableblock > table[frame="void"] {
441 border-style: none;
442}
443div.tableblock > table[frame="hsides"] {
444 border-left-style: none;
445 border-right-style: none;
446}
447div.tableblock > table[frame="vsides"] {
448 border-top-style: none;
449 border-bottom-style: none;
450}
451
452
453/*
454 * html5 specific
455 *
456 * */
457
458table.tableblock {
459 margin-top: 1.0em;
460 margin-bottom: 1.5em;
461}
462thead, p.tableblock.header {
463 font-weight: bold;
464 color: #527bbd;
465}
466p.tableblock {
467 margin-top: 0;
468}
469table.tableblock {
470 border-width: 3px;
471 border-spacing: 0px;
472 border-style: solid;
473 border-color: #527bbd;
474 border-collapse: collapse;
475}
476th.tableblock, td.tableblock {
477 border-width: 1px;
478 padding: 4px;
479 border-style: solid;
480 border-color: #527bbd;
481}
482
483table.tableblock.frame-topbot {
484 border-left-style: hidden;
485 border-right-style: hidden;
486}
487table.tableblock.frame-sides {
488 border-top-style: hidden;
489 border-bottom-style: hidden;
490}
491table.tableblock.frame-none {
492 border-style: hidden;
493}
494
495th.tableblock.halign-left, td.tableblock.halign-left {
496 text-align: left;
497}
498th.tableblock.halign-center, td.tableblock.halign-center {
499 text-align: center;
500}
501th.tableblock.halign-right, td.tableblock.halign-right {
502 text-align: right;
503}
504
505th.tableblock.valign-top, td.tableblock.valign-top {
506 vertical-align: top;
507}
508th.tableblock.valign-middle, td.tableblock.valign-middle {
509 vertical-align: middle;
510}
511th.tableblock.valign-bottom, td.tableblock.valign-bottom {
512 vertical-align: bottom;
513}
514
515
516/*
517 * manpage specific
518 *
519 * */
520
521body.manpage h1 {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]522 padding-top: 0.5em;
523 padding-bottom: 0.5em;
524 border-top: 2px solid silver;
525 border-bottom: 2px solid silver;
526}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]527body.manpage h2 {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]528 border-style: none;
529}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]530body.manpage div.sectionbody {
531 margin-left: 3em;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]532}
533
534@media print {
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]535 body.manpage div#toc { display: none; }
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]536}
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]537
538
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]539</style>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]540<script type="text/javascript">
541/*<![CDATA[*/
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]542var asciidoc = { // Namespace.
543
544/////////////////////////////////////////////////////////////////////
545// Table Of Contents generator
546/////////////////////////////////////////////////////////////////////
547
548/* Author: Mihai Bazon, September 2002
549 * http://students.infoiasi.ro/~mishoo
550 *
551 * Table Of Content generator
552 * Version: 0.4
553 *
554 * Feel free to use this script under the terms of the GNU General Public
555 * License, as long as you do not remove or alter this notice.
556 */
557
558 /* modified by Troy D. Hanson, September 2006. License: GPL */
559 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
560
561// toclevels = 1..4.
562toc: function (toclevels) {
563
564 function getText(el) {
565 var text = "";
566 for (var i = el.firstChild; i != null; i = i.nextSibling) {
567 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
568 text += i.data;
569 else if (i.firstChild != null)
570 text += getText(i);
571 }
572 return text;
573 }
574
575 function TocEntry(el, text, toclevel) {
576 this.element = el;
577 this.text = text;
578 this.toclevel = toclevel;
579 }
580
581 function tocEntries(el, toclevels) {
582 var result = new Array;
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]583 var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]584 // Function that scans the DOM tree for header elements (the DOM2
585 // nodeIterator API would be a better technique but not supported by all
586 // browsers).
587 var iterate = function (el) {
588 for (var i = el.firstChild; i != null; i = i.nextSibling) {
589 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
590 var mo = re.exec(i.tagName);
591 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
592 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
593 }
594 iterate(i);
595 }
596 }
597 }
598 iterate(el);
599 return result;
600 }
601
602 var toc = document.getElementById("toc");
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]603 if (!toc) {
604 return;
605 }
606
607 // Delete existing TOC entries in case we're reloading the TOC.
608 var tocEntriesToRemove = [];
609 var i;
610 for (i = 0; i < toc.childNodes.length; i++) {
611 var entry = toc.childNodes[i];
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]612 if (entry.nodeName.toLowerCase() == 'div'
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]613 && entry.getAttribute("class")
614 && entry.getAttribute("class").match(/^toclevel/))
615 tocEntriesToRemove.push(entry);
616 }
617 for (i = 0; i < tocEntriesToRemove.length; i++) {
618 toc.removeChild(tocEntriesToRemove[i]);
619 }
620
621 // Rebuild TOC entries.
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]622 var entries = tocEntries(document.getElementById("content"), toclevels);
623 for (var i = 0; i < entries.length; ++i) {
624 var entry = entries[i];
625 if (entry.element.id == "")
626 entry.element.id = "_toc_" + i;
627 var a = document.createElement("a");
628 a.href = "#" + entry.element.id;
629 a.appendChild(document.createTextNode(entry.text));
630 var div = document.createElement("div");
631 div.appendChild(a);
632 div.className = "toclevel" + entry.toclevel;
633 toc.appendChild(div);
634 }
635 if (entries.length == 0)
636 toc.parentNode.removeChild(toc);
637},
638
639
640/////////////////////////////////////////////////////////////////////
641// Footnotes generator
642/////////////////////////////////////////////////////////////////////
643
644/* Based on footnote generation code from:
645 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
646 */
647
648footnotes: function () {
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]649 // Delete existing footnote entries in case we're reloading the footnodes.
650 var i;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]651 var noteholder = document.getElementById("footnotes");
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]652 if (!noteholder) {
653 return;
654 }
655 var entriesToRemove = [];
656 for (i = 0; i < noteholder.childNodes.length; i++) {
657 var entry = noteholder.childNodes[i];
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]658 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]659 entriesToRemove.push(entry);
660 }
661 for (i = 0; i < entriesToRemove.length; i++) {
662 noteholder.removeChild(entriesToRemove[i]);
663 }
664
665 // Rebuild footnote entries.
666 var cont = document.getElementById("content");
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]667 var spans = cont.getElementsByTagName("span");
668 var refs = {};
669 var n = 0;
670 for (i=0; i<spans.length; i++) {
671 if (spans[i].className == "footnote") {
672 n++;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]673 var note = spans[i].getAttribute("data-note");
674 if (!note) {
675 // Use [\s\S] in place of . so multi-line matches work.
676 // Because JavaScript has no s (dotall) regex flag.
677 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
678 spans[i].innerHTML =
679 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
680 "' title='View footnote' class='footnote'>" + n + "</a>]";
681 spans[i].setAttribute("data-note", note);
682 }
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]683 noteholder.innerHTML +=
684 "<div class='footnote' id='_footnote_" + n + "'>" +
685 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
686 n + "</a>. " + note + "</div>";
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]687 var id =spans[i].getAttribute("id");
688 if (id != null) refs["#"+id] = n;
689 }
690 }
691 if (n == 0)
692 noteholder.parentNode.removeChild(noteholder);
693 else {
694 // Process footnoterefs.
695 for (i=0; i<spans.length; i++) {
696 if (spans[i].className == "footnoteref") {
697 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
698 href = href.match(/#.*/)[0]; // Because IE return full URL.
699 n = refs[href];
700 spans[i].innerHTML =
701 "[<a href='#_footnote_" + n +
702 "' title='View footnote' class='footnote'>" + n + "</a>]";
703 }
704 }
705 }
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]706},
707
708install: function(toclevels) {
709 var timerId;
710
711 function reinstall() {
712 asciidoc.footnotes();
713 if (toclevels) {
714 asciidoc.toc(toclevels);
715 }
716 }
717
718 function reinstallAndRemoveTimer() {
719 clearInterval(timerId);
720 reinstall();
721 }
722
723 timerId = setInterval(reinstall, 500);
724 if (document.addEventListener)
725 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
726 else
727 window.onload = reinstallAndRemoveTimer;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]728}
729
730}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]731asciidoc.install();
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]732/*]]>*/
733</script>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]734</head>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]735<body class="manpage">
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]736<div id="header">
737<h1>
738git-bisect(1) Manual Page
739</h1>
740<h2>NAME</h2>
741<div class="sectionbody">
742<p>git-bisect -
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]743 Use binary search to find the commit that introduced a bug
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]744</p>
745</div>
746</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]747<div id="content">
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]748<div class="sect1">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]749<h2 id="_synopsis">SYNOPSIS</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]750<div class="sectionbody">
Junio C Hamano15567bc2011-07-23 00:51:59[diff] [blame]751<div class="verseblock">
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]752<pre class="content"><em>git bisect</em> &lt;subcommand&gt; &lt;options&gt;</pre>
753<div class="attribution">
Junio C Hamano15567bc2011-07-23 00:51:59[diff] [blame]754</div></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]755</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]756</div>
757<div class="sect1">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]758<h2 id="_description">DESCRIPTION</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]759<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]760<div class="paragraph"><p>The command takes various subcommands, and different options depending
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]761on the subcommand:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]762<div class="literalblock">
763<div class="content">
Junio C Hamano1eb56092015-10-05 20:39:53[diff] [blame]764<pre><code>git bisect start [--term-{old,good}=&lt;term&gt; --term-{new,bad}=&lt;term&gt;]
765 [--no-checkout] [&lt;bad&gt; [&lt;good&gt;...]] [--] [&lt;paths&gt;...]
Junio C Hamanobcd98f42017-01-24 00:12:16[diff] [blame]766git bisect (bad|new|&lt;term-new&gt;) [&lt;rev&gt;]
767git bisect (good|old|&lt;term-old&gt;) [&lt;rev&gt;...]
Junio C Hamano1eb56092015-10-05 20:39:53[diff] [blame]768git bisect terms [--term-good | --term-bad]
Junio C Hamanod796cea2008-12-03 03:51:10[diff] [blame]769git bisect skip [(&lt;rev&gt;|&lt;range&gt;)...]
Junio C Hamanoc21ab052009-10-31 04:03:55[diff] [blame]770git bisect reset [&lt;commit&gt;]
Junio C Hamanob72f6032017-11-15 05:57:08[diff] [blame]771git bisect (visualize|view)
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]772git bisect replay &lt;logfile&gt;
Junio C Hamanof440a232007-03-23 10:46:17[diff] [blame]773git bisect log
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]774git bisect run &lt;cmd&gt;...
775git bisect help</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]776</div></div>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]777<div class="paragraph"><p>This command uses a binary search algorithm to find which commit in
778your project&#8217;s history introduced a bug. You use it by first telling
779it a "bad" commit that is known to contain the bug, and a "good"
780commit that is known to be before the bug was introduced. Then <code>git
781bisect</code> picks a commit between those two endpoints and asks you
782whether the selected commit is "good" or "bad". It continues narrowing
783down the range until it finds the exact commit that introduced the
784change.</p></div>
Junio C Hamano1eb56092015-10-05 20:39:53[diff] [blame]785<div class="paragraph"><p>In fact, <code>git bisect</code> can be used to find the commit that changed
786<strong>any</strong> property of your project; e.g., the commit that fixed a bug, or
787the commit that caused a benchmark&#8217;s performance to improve. To
788support this more general usage, the terms "old" and "new" can be used
789in place of "good" and "bad", or you can choose your own terms. See
790section "Alternate terms" below for more information.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]791<div class="sect2">
792<h3 id="_basic_bisect_commands_start_bad_good">Basic bisect commands: start, bad, good</h3>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]793<div class="paragraph"><p>As an example, suppose you are trying to find the commit that broke a
794feature that was known to work in version <code>v2.6.13-rc2</code> of your
795project. You start a bisect session as follows:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]796<div class="listingblock">
797<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]798<pre><code>$ git bisect start
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]799$ git bisect bad # Current version is bad
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]800$ git bisect good v2.6.13-rc2 # v2.6.13-rc2 is known to be good</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]801</div></div>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]802<div class="paragraph"><p>Once you have specified at least one bad and one good commit, <code>git
803bisect</code> selects a commit in the middle of that range of history,
804checks it out, and outputs something similar to the following:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]805<div class="listingblock">
806<div class="content">
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]807<pre><code>Bisecting: 675 revisions left to test after this (roughly 10 steps)</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]808</div></div>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]809<div class="paragraph"><p>You should now compile the checked-out version and test it. If that
810version works correctly, type</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]811<div class="listingblock">
812<div class="content">
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]813<pre><code>$ git bisect good</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]814</div></div>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]815<div class="paragraph"><p>If that version is broken, type</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]816<div class="listingblock">
817<div class="content">
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]818<pre><code>$ git bisect bad</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]819</div></div>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]820<div class="paragraph"><p>Then <code>git bisect</code> will respond with something like</p></div>
821<div class="listingblock">
822<div class="content">
823<pre><code>Bisecting: 337 revisions left to test after this (roughly 9 steps)</code></pre>
824</div></div>
825<div class="paragraph"><p>Keep repeating the process: compile the tree, test it, and depending
826on whether it is good or bad run <code>git bisect good</code> or <code>git bisect bad</code>
827to ask for the next commit that needs testing.</p></div>
828<div class="paragraph"><p>Eventually there will be no more revisions left to inspect, and the
829command will print out a description of the first bad commit. The
830reference <code>refs/bisect/bad</code> will be left pointing at that commit.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]831</div>
832<div class="sect2">
833<h3 id="_bisect_reset">Bisect reset</h3>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]834<div class="paragraph"><p>After a bisect session, to clean up the bisection state and return to
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]835the original HEAD, issue the following command:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]836<div class="listingblock">
837<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]838<pre><code>$ git bisect reset</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]839</div></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]840<div class="paragraph"><p>By default, this will return your tree to the commit that was checked
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]841out before <code>git bisect start</code>. (A new <code>git bisect start</code> will also do
Junio C Hamanoc21ab052009-10-31 04:03:55[diff] [blame]842that, as it cleans up the old bisection state.)</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]843<div class="paragraph"><p>With an optional argument, you can return to a different commit
Junio C Hamanoc21ab052009-10-31 04:03:55[diff] [blame]844instead:</p></div>
845<div class="listingblock">
846<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]847<pre><code>$ git bisect reset &lt;commit&gt;</code></pre>
Junio C Hamanoc21ab052009-10-31 04:03:55[diff] [blame]848</div></div>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]849<div class="paragraph"><p>For example, <code>git bisect reset bisect/bad</code> will check out the first
850bad revision, while <code>git bisect reset HEAD</code> will leave you on the
851current bisection commit and avoid switching commits at all.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]852</div>
853<div class="sect2">
Junio C Hamano1eb56092015-10-05 20:39:53[diff] [blame]854<h3 id="_alternate_terms">Alternate terms</h3>
855<div class="paragraph"><p>Sometimes you are not looking for the commit that introduced a
856breakage, but rather for a commit that caused a change between some
857other "old" state and "new" state. For example, you might be looking
858for the commit that introduced a particular fix. Or you might be
859looking for the first commit in which the source-code filenames were
860finally all converted to your company&#8217;s naming standard. Or whatever.</p></div>
861<div class="paragraph"><p>In such cases it can be very confusing to use the terms "good" and
862"bad" to refer to "the state before the change" and "the state after
863the change". So instead, you can use the terms "old" and "new",
864respectively, in place of "good" and "bad". (But note that you cannot
865mix "good" and "bad" with "old" and "new" in a single session.)</p></div>
866<div class="paragraph"><p>In this more general usage, you provide <code>git bisect</code> with a "new"
Junio C Hamano761b4812017-04-17 07:27:59[diff] [blame]867commit that has some property and an "old" commit that doesn&#8217;t have that
Junio C Hamano1eb56092015-10-05 20:39:53[diff] [blame]868property. Each time <code>git bisect</code> checks out a commit, you test if that
869commit has the property. If it does, mark the commit as "new";
870otherwise, mark it as "old". When the bisection is done, <code>git bisect</code>
871will report which commit introduced the property.</p></div>
872<div class="paragraph"><p>To use "old" and "new" instead of "good" and bad, you must run <code>git
873bisect start</code> without commits as argument and then run the following
874commands to add the commits:</p></div>
875<div class="listingblock">
876<div class="content">
877<pre><code>git bisect old [&lt;rev&gt;]</code></pre>
878</div></div>
879<div class="paragraph"><p>to indicate that a commit was before the sought change, or</p></div>
880<div class="listingblock">
881<div class="content">
882<pre><code>git bisect new [&lt;rev&gt;...]</code></pre>
883</div></div>
884<div class="paragraph"><p>to indicate that it was after.</p></div>
885<div class="paragraph"><p>To get a reminder of the currently used terms, use</p></div>
886<div class="listingblock">
887<div class="content">
888<pre><code>git bisect terms</code></pre>
889</div></div>
Junio C Hamano96153bf2018-04-25 08:25:34[diff] [blame]890<div class="paragraph"><p>You can get just the old (respectively new) term with <code>git bisect terms
891--term-old</code> or <code>git bisect terms --term-good</code>.</p></div>
Junio C Hamano1eb56092015-10-05 20:39:53[diff] [blame]892<div class="paragraph"><p>If you would like to use your own terms instead of "bad"/"good" or
893"new"/"old", you can choose any names you like (except existing bisect
894subcommands like <code>reset</code>, <code>start</code>, &#8230;) by starting the
895bisection using</p></div>
896<div class="listingblock">
897<div class="content">
898<pre><code>git bisect start --term-old &lt;term-old&gt; --term-new &lt;term-new&gt;</code></pre>
899</div></div>
900<div class="paragraph"><p>For example, if you are looking for a commit that introduced a
901performance regression, you might use</p></div>
902<div class="listingblock">
903<div class="content">
904<pre><code>git bisect start --term-old fast --term-new slow</code></pre>
905</div></div>
906<div class="paragraph"><p>Or if you are looking for the commit that fixed a bug, you might use</p></div>
907<div class="listingblock">
908<div class="content">
909<pre><code>git bisect start --term-new fixed --term-old broken</code></pre>
910</div></div>
911<div class="paragraph"><p>Then, use <code>git bisect &lt;term-old&gt;</code> and <code>git bisect &lt;term-new&gt;</code> instead
912of <code>git bisect good</code> and <code>git bisect bad</code> to mark commits.</p></div>
913</div>
914<div class="sect2">
Junio C Hamanob72f6032017-11-15 05:57:08[diff] [blame]915<h3 id="_bisect_visualize_view">Bisect visualize/view</h3>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]916<div class="paragraph"><p>To see the currently remaining suspects in <em>gitk</em>, issue the following
Junio C Hamanob72f6032017-11-15 05:57:08[diff] [blame]917command during the bisection process (the subcommand <code>view</code> can be used
918as an alternative to <code>visualize</code>):</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]919<div class="listingblock">
920<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]921<pre><code>$ git bisect visualize</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]922</div></div>
Junio C Hamano042f2142016-06-27 18:05:05[diff] [blame]923<div class="paragraph"><p>If the <code>DISPLAY</code> environment variable is not set, <em>git log</em> is used
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]924instead. You can also give command-line options such as <code>-p</code> and
925<code>--stat</code>.</p></div>
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]926<div class="listingblock">
927<div class="content">
Junio C Hamanob72f6032017-11-15 05:57:08[diff] [blame]928<pre><code>$ git bisect visualize --stat</code></pre>
Junio C Hamano942b35e2007-12-09 10:19:33[diff] [blame]929</div></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]930</div>
931<div class="sect2">
932<h3 id="_bisect_log_and_bisect_replay">Bisect log and bisect replay</h3>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]933<div class="paragraph"><p>After having marked revisions as good or bad, issue the following
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]934command to show what has been done so far:</p></div>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]935<div class="listingblock">
936<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]937<pre><code>$ git bisect log</code></pre>
Junio C Hamanob60308a2007-03-24 07:16:42[diff] [blame]938</div></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]939<div class="paragraph"><p>If you discover that you made a mistake in specifying the status of a
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]940revision, you can save the output of this command to a file, edit it to
941remove the incorrect entries, and then issue the following commands to
942return to a corrected state:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]943<div class="listingblock">
944<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]945<pre><code>$ git bisect reset
946$ git bisect replay that-file</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]947</div></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]948</div>
949<div class="sect2">
950<h3 id="_avoiding_testing_a_commit">Avoiding testing a commit</h3>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]951<div class="paragraph"><p>If, in the middle of a bisect session, you know that the suggested
952revision is not a good one to test (e.g. it fails to build and you
953know that the failure does not have anything to do with the bug you
954are chasing), you can manually select a nearby commit and test that
955one instead.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]956<div class="paragraph"><p>For example:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]957<div class="listingblock">
958<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]959<pre><code>$ git bisect good/bad # previous round was good or bad.
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]960Bisecting: 337 revisions left to test after this (roughly 9 steps)
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]961$ git bisect visualize # oops, that is uninteresting.
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]962$ git reset --hard HEAD~3 # try 3 revisions before what
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]963 # was suggested</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]964</div></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]965<div class="paragraph"><p>Then compile and test the chosen revision, and afterwards mark
Junio C Hamano1de75722009-03-26 08:39:38[diff] [blame]966the revision as good or bad in the usual manner.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]967</div>
968<div class="sect2">
969<h3 id="_bisect_skip">Bisect skip</h3>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]970<div class="paragraph"><p>Instead of choosing a nearby commit by yourself, you can ask Git to do
971it for you by issuing the command:</p></div>
Junio C Hamano1974bf22007-10-31 05:57:20[diff] [blame]972<div class="listingblock">
973<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]974<pre><code>$ git bisect skip # Current version cannot be tested</code></pre>
Junio C Hamano1974bf22007-10-31 05:57:20[diff] [blame]975</div></div>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]976<div class="paragraph"><p>However, if you skip a commit adjacent to the one you are looking for,
977Git will be unable to tell exactly which of those commits was the
978first bad one.</p></div>
979<div class="paragraph"><p>You can also skip a range of commits, instead of just one commit,
980using range notation. For example:</p></div>
Junio C Hamanod796cea2008-12-03 03:51:10[diff] [blame]981<div class="listingblock">
982<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]983<pre><code>$ git bisect skip v2.5..v2.6</code></pre>
Junio C Hamanod796cea2008-12-03 03:51:10[diff] [blame]984</div></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]985<div class="paragraph"><p>This tells the bisect process that no commit after <code>v2.5</code>, up to and
986including <code>v2.6</code>, should be tested.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]987<div class="paragraph"><p>Note that if you also want to skip the first commit of the range you
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]988would issue the command:</p></div>
Junio C Hamanod796cea2008-12-03 03:51:10[diff] [blame]989<div class="listingblock">
990<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]991<pre><code>$ git bisect skip v2.5 v2.5..v2.6</code></pre>
Junio C Hamanod796cea2008-12-03 03:51:10[diff] [blame]992</div></div>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]993<div class="paragraph"><p>This tells the bisect process that the commits between <code>v2.5</code> and
994<code>v2.6</code> (inclusive) should be skipped.</p></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]995</div>
996<div class="sect2">
997<h3 id="_cutting_down_bisection_by_giving_more_parameters_to_bisect_start">Cutting down bisection by giving more parameters to bisect start</h3>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]998<div class="paragraph"><p>You can further cut down the number of trials, if you know what part of
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]999the tree is involved in the problem you are tracking down, by specifying
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1000path parameters when issuing the <code>bisect start</code> command:</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1001<div class="listingblock">
1002<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1003<pre><code>$ git bisect start -- arch/i386 include/asm-i386</code></pre>
Junio C Hamano12a3a232007-04-07 10:18:10[diff] [blame]1004</div></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]1005<div class="paragraph"><p>If you know beforehand more than one good commit, you can narrow the
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]1006bisect space down by specifying all of the good commits immediately after
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1007the bad commit when issuing the <code>bisect start</code> command:</p></div>
Junio C Hamano12a3a232007-04-07 10:18:10[diff] [blame]1008<div class="listingblock">
1009<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1010<pre><code>$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
Junio C Hamano12a3a232007-04-07 10:18:10[diff] [blame]1011 # v2.6.20-rc6 is bad
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1012 # v2.6.20-rc4 and v2.6.20-rc1 are good</code></pre>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1013</div></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1014</div>
1015<div class="sect2">
1016<h3 id="_bisect_run">Bisect run</h3>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]1017<div class="paragraph"><p>If you have a script that can tell if the current source code is good
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]1018or bad, you can bisect by issuing the command:</p></div>
Junio C Hamanof440a232007-03-23 10:46:17[diff] [blame]1019<div class="listingblock">
1020<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1021<pre><code>$ git bisect run my_script arguments</code></pre>
Junio C Hamanof440a232007-03-23 10:46:17[diff] [blame]1022</div></div>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]1023<div class="paragraph"><p>Note that the script (<code>my_script</code> in the above example) should exit
1024with code 0 if the current source code is good/old, and exit with a
1025code between 1 and 127 (inclusive), except 125, if the current source
1026code is bad/new.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]1027<div class="paragraph"><p>Any other exit code will abort the bisect process. It should be noted
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]1028that a program that terminates via <code>exit(-1)</code> leaves $? = 255, (see the
1029exit(3) manual page), as the value is chopped with <code>&amp; 0377</code>.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]1030<div class="paragraph"><p>The special exit code 125 should be used when the current source code
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]1031cannot be tested. If the script exits with this code, the current
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1032revision will be skipped (see <code>git bisect skip</code> above). 125 was chosen
Junio C Hamanod2c978f2011-03-20 19:42:22[diff] [blame]1033as the highest sensible value to use for this purpose, because 126 and 127
1034are used by POSIX shells to signal specific error status (127 is for
Junio C Hamanoee615802015-10-29 21:45:26[diff] [blame]1035command not found, 126 is for command found but not executable&#8212;these
Junio C Hamanod2c978f2011-03-20 19:42:22[diff] [blame]1036details do not matter, as they are normal errors in the script, as far as
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]1037<code>bisect run</code> is concerned).</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]1038<div class="paragraph"><p>You may often find that during a bisect session you want to have
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]1039temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a
1040header file, or "revision that does not have this commit needs this
1041patch applied to work around another problem this bisection is not
1042interested in") applied to the revision being tested.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]1043<div class="paragraph"><p>To cope with such a situation, after the inner <em>git bisect</em> finds the
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]1044next revision to test, the script can apply the patch
1045before compiling, run the real test, and afterwards decide if the
1046revision (possibly with the needed patch) passed the test and then
1047rewind the tree to the pristine state. Finally the script should exit
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]1048with the status of the real test to let the <code>git bisect run</code> command loop
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]1049determine the eventual outcome of the bisect session.</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1050</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1051</div>
1052</div>
1053<div class="sect1">
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1054<h2 id="_options">OPTIONS</h2>
1055<div class="sectionbody">
1056<div class="dlist"><dl>
1057<dt class="hdlist1">
1058--no-checkout
1059</dt>
1060<dd>
1061<div class="paragraph"><p>Do not checkout the new working tree at each iteration of the bisection
Junio C Hamano92d80372016-07-13 22:00:05[diff] [blame]1062process. Instead just update a special reference named <code>BISECT_HEAD</code> to make
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1063it point to the commit that should be tested.</p></div>
1064<div class="paragraph"><p>This option may be useful when the test you would perform in each step
1065does not require a checked out tree.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1066<div class="paragraph"><p>If the repository is bare, <code>--no-checkout</code> is assumed.</p></div>
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1067</dd>
1068</dl></div>
1069</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1070</div>
1071<div class="sect1">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1072<h2 id="_examples">EXAMPLES</h2>
Junio C Hamano6d76d612008-05-09 05:46:08[diff] [blame]1073<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]1074<div class="ulist"><ul>
Junio C Hamano6d76d612008-05-09 05:46:08[diff] [blame]1075<li>
1076<p>
1077Automatically bisect a broken build between v1.2 and HEAD:
1078</p>
1079<div class="listingblock">
1080<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1081<pre><code>$ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good
Junio C Hamano97cc08f2013-02-14 21:11:15[diff] [blame]1082$ git bisect run make # "make" builds the app
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1083$ git bisect reset # quit the bisect session</code></pre>
Junio C Hamano6d76d612008-05-09 05:46:08[diff] [blame]1084</div></div>
1085</li>
1086<li>
1087<p>
Junio C Hamano0a235222009-03-06 08:21:09[diff] [blame]1088Automatically bisect a test failure between origin and HEAD:
1089</p>
1090<div class="listingblock">
1091<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1092<pre><code>$ git bisect start HEAD origin -- # HEAD is bad, origin is good
Junio C Hamano97cc08f2013-02-14 21:11:15[diff] [blame]1093$ git bisect run make test # "make test" builds and tests
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1094$ git bisect reset # quit the bisect session</code></pre>
Junio C Hamano0a235222009-03-06 08:21:09[diff] [blame]1095</div></div>
1096</li>
1097<li>
1098<p>
Junio C Hamano6d76d612008-05-09 05:46:08[diff] [blame]1099Automatically bisect a broken test case:
1100</p>
1101<div class="listingblock">
1102<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1103<pre><code>$ cat ~/test.sh
Junio C Hamano6d76d612008-05-09 05:46:08[diff] [blame]1104#!/bin/sh
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]1105make || exit 125 # this skips broken builds
Junio C Hamano9a2fb2d2011-03-23 05:40:15[diff] [blame]1106~/check_test_case.sh # does the test case pass?
Junio C Hamano6d76d612008-05-09 05:46:08[diff] [blame]1107$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10
Junio C Hamano97cc08f2013-02-14 21:11:15[diff] [blame]1108$ git bisect run ~/test.sh
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1109$ git bisect reset # quit the bisect session</code></pre>
Junio C Hamano6d76d612008-05-09 05:46:08[diff] [blame]1110</div></div>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]1111<div class="paragraph"><p>Here we use a <code>test.sh</code> custom script. In this script, if <code>make</code>
Junio C Hamano9a2fb2d2011-03-23 05:40:15[diff] [blame]1112fails, we skip the current commit.
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]1113<code>check_test_case.sh</code> should <code>exit 0</code> if the test case passes,
1114and <code>exit 1</code> otherwise.</p></div>
1115<div class="paragraph"><p>It is safer if both <code>test.sh</code> and <code>check_test_case.sh</code> are
Junio C Hamanofd83b8e2009-03-22 08:21:41[diff] [blame]1116outside the repository to prevent interactions between the bisect,
1117make and test processes and the scripts.</p></div>
Junio C Hamano6d76d612008-05-09 05:46:08[diff] [blame]1118</li>
Junio C Hamano0a235222009-03-06 08:21:09[diff] [blame]1119<li>
1120<p>
Junio C Hamano9a2fb2d2011-03-23 05:40:15[diff] [blame]1121Automatically bisect with temporary modifications (hot-fix):
1122</p>
1123<div class="listingblock">
1124<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1125<pre><code>$ cat ~/test.sh
Junio C Hamano9a2fb2d2011-03-23 05:40:15[diff] [blame]1126#!/bin/sh
1127
1128# tweak the working tree by merging the hot-fix branch
1129# and then attempt a build
Junio C Hamano8ef91f32019-12-01 22:58:27[diff] [blame]1130if git merge --no-commit --no-ff hot-fix &amp;&amp;
Junio C Hamano9a2fb2d2011-03-23 05:40:15[diff] [blame]1131 make
1132then
1133 # run project specific test and report its status
1134 ~/check_test_case.sh
1135 status=$?
1136else
1137 # tell the caller this is untestable
1138 status=125
1139fi
1140
1141# undo the tweak to allow clean flipping to the next commit
1142git reset --hard
1143
1144# return control
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1145exit $status</code></pre>
Junio C Hamano9a2fb2d2011-03-23 05:40:15[diff] [blame]1146</div></div>
1147<div class="paragraph"><p>This applies modifications from a hot-fix branch before each test run,
1148e.g. in case your build or test environment changed so that older
1149revisions may need a fix which newer ones have already. (Make sure the
1150hot-fix branch is based off a commit which is contained in all revisions
1151which you are bisecting, so that the merge does not pull in too much, or
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1152use <code>git cherry-pick</code> instead of <code>git merge</code>.)</p></div>
Junio C Hamano9a2fb2d2011-03-23 05:40:15[diff] [blame]1153</li>
1154<li>
1155<p>
1156Automatically bisect a broken test case:
Junio C Hamano0a235222009-03-06 08:21:09[diff] [blame]1157</p>
1158<div class="listingblock">
1159<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1160<pre><code>$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10
Junio C Hamano97cc08f2013-02-14 21:11:15[diff] [blame]1161$ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1162$ git bisect reset # quit the bisect session</code></pre>
Junio C Hamano0a235222009-03-06 08:21:09[diff] [blame]1163</div></div>
Junio C Hamano9a2fb2d2011-03-23 05:40:15[diff] [blame]1164<div class="paragraph"><p>This shows that you can do without a run script if you write the test
1165on a single line.</p></div>
Junio C Hamano0a235222009-03-06 08:21:09[diff] [blame]1166</li>
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1167<li>
1168<p>
1169Locate a good region of the object graph in a damaged repository
1170</p>
1171<div class="listingblock">
1172<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1173<pre><code>$ git bisect start HEAD &lt;known-good-commit&gt; [ &lt;boundary-commit&gt; ... ] --no-checkout
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1174$ git bisect run sh -c '
1175 GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) &amp;&amp;
1176 git rev-list --objects BISECT_HEAD --not $GOOD &gt;tmp.$$ &amp;&amp;
1177 git pack-objects --stdout &gt;/dev/null &lt;tmp.$$
1178 rc=$?
1179 rm -f tmp.$$
Junio C Hamano97cc08f2013-02-14 21:11:15[diff] [blame]1180 test $rc = 0'
1181
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1182$ git bisect reset # quit the bisect session</code></pre>
Junio C Hamanof7279012011-08-18 06:13:13[diff] [blame]1183</div></div>
1184<div class="paragraph"><p>In this case, when <em>git bisect run</em> finishes, bisect/bad will refer to a commit that
1185has at least one parent whose reachable graph is fully traversable in the sense
1186required by <em>git pack objects</em>.</p></div>
1187</li>
Junio C Hamano1eb56092015-10-05 20:39:53[diff] [blame]1188<li>
1189<p>
1190Look for a fix instead of a regression in the code
1191</p>
1192<div class="listingblock">
1193<div class="content">
1194<pre><code>$ git bisect start
1195$ git bisect new HEAD # current commit is marked as new
1196$ git bisect old HEAD~10 # the tenth commit from now is marked as old</code></pre>
1197</div></div>
1198<div class="paragraph"><p>or:</p></div>
1199</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1200</ul></div>
Junio C Hamano1eb56092015-10-05 20:39:53[diff] [blame]1201<div class="listingblock">
1202<div class="content">
1203<pre><code>$ git bisect start --term-old broken --term-new fixed
1204$ git bisect fixed
1205$ git bisect broken HEAD~10</code></pre>
1206</div></div>
Junio C Hamano9c512872015-08-12 21:59:25[diff] [blame]1207<div class="sect2">
1208<h3 id="_getting_help">Getting help</h3>
1209<div class="paragraph"><p>Use <code>git bisect</code> to get a short usage description, and <code>git bisect
1210help</code> or <code>git bisect -h</code> to get a long usage description.</p></div>
1211</div>
Junio C Hamano6d76d612008-05-09 05:46:08[diff] [blame]1212</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1213</div>
1214<div class="sect1">
Junio C Hamano2bd8a742009-12-01 21:16:59[diff] [blame]1215<h2 id="_see_also">SEE ALSO</h2>
1216<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]1217<div class="paragraph"><p><a href="git-bisect-lk2009.html">Fighting regressions with git bisect</a>,
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]1218<a href="git-blame.html">git-blame(1)</a>.</p></div>
Junio C Hamano2bd8a742009-12-01 21:16:59[diff] [blame]1219</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1220</div>
1221<div class="sect1">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1222<h2 id="_git">GIT</h2>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1223<div class="sectionbody">
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]1224<div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1225</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]1226</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1227</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]1228<div id="footnotes"><hr /></div>
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1229<div id="footer">
1230<div id="footer-text">
Junio C Hamano2ef0ba32018-01-26 23:13:53[diff] [blame]1231Last updated
Junio C Hamano7a46cd62020-03-15 21:57:10[diff] [blame]1232 2020-03-10 08:03:13 PDT
Junio C Hamano1a4e8412005-12-27 08:17:23[diff] [blame]1233</div>
1234</div>
1235</body>
1236</html>