]>
Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-bisect(1) |
2 | ============= | |
7fc9d69f JH |
3 | |
4 | NAME | |
5 | ---- | |
215a7ad1 | 6 | git-bisect - Find the change that introduced a bug |
7fc9d69f JH |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
556cb4e5 | 11 | 'git bisect' <subcommand> <options> |
7fc9d69f JH |
12 | |
13 | DESCRIPTION | |
14 | ----------- | |
556cb4e5 JH |
15 | The command takes various subcommands, and different options |
16 | depending on the subcommand: | |
17 | ||
18 | git bisect start [<paths>...] | |
19 | git bisect bad <rev> | |
20 | git bisect good <rev> | |
21 | git bisect reset [<branch>] | |
22 | git bisect visualize | |
23 | git bisect replay <logfile> | |
24 | git bisect log | |
25 | ||
f85a4191 JH |
26 | This command uses 'git-rev-list --bisect' option to help drive |
27 | the binary search process to find which change introduced a bug, | |
28 | given an old "good" commit object name and a later "bad" commit | |
29 | object name. | |
7fc9d69f | 30 | |
f85a4191 | 31 | The way you use it is: |
7fc9d69f | 32 | |
f85a4191 | 33 | ------------------------------------------------ |
556cb4e5 JH |
34 | $ git bisect start |
35 | $ git bisect bad # Current version is bad | |
36 | $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version | |
37 | # tested that was good | |
f85a4191 | 38 | ------------------------------------------------ |
7fc9d69f | 39 | |
f85a4191 JH |
40 | When you give at least one bad and one good versions, it will |
41 | bisect the revision tree and say something like: | |
42 | ||
43 | ------------------------------------------------ | |
44 | Bisecting: 675 revisions left to test after this | |
45 | ------------------------------------------------ | |
46 | ||
47 | and check out the state in the middle. Now, compile that kernel, and boot | |
48 | it. Now, let's say that this booted kernel works fine, then just do | |
49 | ||
50 | ------------------------------------------------ | |
556cb4e5 | 51 | $ git bisect good # this one is good |
f85a4191 JH |
52 | ------------------------------------------------ |
53 | ||
54 | which will now say | |
55 | ||
56 | ------------------------------------------------ | |
57 | Bisecting: 337 revisions left to test after this | |
58 | ------------------------------------------------ | |
59 | ||
60 | and you continue along, compiling that one, testing it, and depending on | |
61 | whether it is good or bad, you say "git bisect good" or "git bisect bad", | |
62 | and ask for the next bisection. | |
63 | ||
64 | Until you have no more left, and you'll have been left with the first bad | |
65 | kernel rev in "refs/bisect/bad". | |
66 | ||
67 | Oh, and then after you want to reset to the original head, do a | |
68 | ||
69 | ------------------------------------------------ | |
556cb4e5 | 70 | $ git bisect reset |
f85a4191 JH |
71 | ------------------------------------------------ |
72 | ||
73 | to get back to the master branch, instead of being in one of the bisection | |
74 | branches ("git bisect start" will do that for you too, actually: it will | |
75 | reset the bisection state, and before it does that it checks that you're | |
76 | not using some old bisection branch). | |
7fc9d69f | 77 | |
8db9307c JH |
78 | During the bisection process, you can say |
79 | ||
556cb4e5 JH |
80 | ------------ |
81 | $ git bisect visualize | |
82 | ------------ | |
8db9307c JH |
83 | |
84 | to see the currently remaining suspects in `gitk`. | |
85 | ||
f73ae1fc | 86 | The good/bad input is logged, and `git bisect |
b595ed14 JH |
87 | log` shows what you have done so far. You can truncate its |
88 | output somewhere and save it in a file, and run | |
89 | ||
556cb4e5 JH |
90 | ------------ |
91 | $ git bisect replay that-file | |
92 | ------------ | |
b595ed14 JH |
93 | |
94 | if you find later you made a mistake telling good/bad about a | |
95 | revision. | |
96 | ||
556cb4e5 JH |
97 | If in a middle of bisect session, you know what the bisect |
98 | suggested to try next is not a good one to test (e.g. the change | |
99 | the commit introduces is known not to work in your environment | |
100 | and you know it does not have anything to do with the bug you | |
101 | are chasing), you may want to find a near-by commit and try that | |
102 | instead. It goes something like this: | |
103 | ||
104 | ------------ | |
105 | $ git bisect good/bad # previous round was good/bad. | |
106 | Bisecting: 337 revisions left to test after this | |
107 | $ git bisect visualize # oops, that is uninteresting. | |
108 | $ git reset --hard HEAD~3 # try 3 revs before what | |
109 | # was suggested | |
110 | ------------ | |
111 | ||
112 | Then compile and test the one you chose to try. After that, | |
113 | tell bisect what the result was as usual. | |
114 | ||
115 | You can further cut down the number of trials if you know what | |
116 | part of the tree is involved in the problem you are tracking | |
117 | down, by giving paths parameters when you say `bisect start`, | |
118 | like this: | |
119 | ||
120 | ------------ | |
121 | $ git bisect start arch/i386 include/asm-i386 | |
122 | ------------ | |
123 | ||
7fc9d69f JH |
124 | |
125 | Author | |
126 | ------ | |
127 | Written by Linus Torvalds <torvalds@osdl.org> | |
128 | ||
129 | Documentation | |
df8baa42 | 130 | ------------- |
7fc9d69f JH |
131 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. |
132 | ||
133 | GIT | |
134 | --- | |
a7154e91 | 135 | Part of the gitlink:git[7] suite |
7fc9d69f | 136 |