236425919b · matheusbsbs/matheus-bagliano

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

3

4 NAME

5 ----

6 -git-bisect - Find the change that introduced a bug by binary search

6 +git-bisect - Find by binary search the change that introduced a bug

7

8

9 SYNOPSIS

@@ -39,7 +39,8 @@ help" or "git bisect -h" to get a long usage description.

39 Basic bisect commands: start, bad, good

40 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

41

42 -The way you use it is:

42 +Using the Linux kernel tree as an example, basic use of the bisect

43 +command is as follows:

44

45 ------------------------------------------------

46 $ git bisect start

@@ -48,61 +49,62 @@ $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version

49 # tested that was good

50 ------------------------------------------------

51

51 -When you give at least one bad and one good versions, it will bisect

52 -the revision tree and say something like:

52 +When you have specified at least one bad and one good version, the

53 +command bisects the revision tree and outputs something similar to:

54

55 ------------------------------------------------

56 Bisecting: 675 revisions left to test after this

57 ------------------------------------------------

58

58 -and check out the state in the middle. Now, compile that kernel, and

59 -boot it. Now, let's say that this booted kernel works fine, then just

60 -do

59 +and then checks out the state in the middle. You would now compile

60 +that kernel and boot it. If the booted kernel works correctly, you

61 +would then issue the following command:

62

63 ------------------------------------------------

64 $ git bisect good # this one is good

65 ------------------------------------------------

66

66 -which will now say

67 +which would then output something similar to:

68

69 ------------------------------------------------

70 Bisecting: 337 revisions left to test after this

71 ------------------------------------------------

72

73 and you continue along, compiling that one, testing it, and depending

73 -on whether it is good or bad, you say "git bisect good" or "git bisect

74 -bad", and ask for the next bisection.

74 +on whether it is good or bad issuing the command "git bisect good"

75 +or "git bisect bad" to ask for the next bisection.

76

76 -Until you have no more left, and you'll have been left with the first

77 -bad kernel rev in "refs/bisect/bad".

77 +Eventually there will be no more revisions left to bisect, and you

78 +will have been left with the first bad kernel revision in "refs/bisect/bad".

79

80 Bisect reset

81 ~~~~~~~~~~~~

82

82 -Oh, and then after you want to reset to the original head, do a

83 +To return to the original head after a bisect session, you issue the

84 +command:

85

86 ------------------------------------------------

87 $ git bisect reset

88 ------------------------------------------------

89

88 -to get back to the original branch, instead of being on the bisection

89 -commit ("git bisect start" will do that for you too, actually: it will

90 -reset the bisection state).

90 +This resets the tree to the original branch instead of being on the

91 +bisection commit ("git bisect start" will also do that, as it resets

92 +the bisection state).

93

94 Bisect visualize

95 ~~~~~~~~~~~~~~~~

96

95 -During the bisection process, you can say

97 +During the bisection process, you issue the command:

98

99 ------------

100 $ git bisect visualize

101 ------------

102

101 -to see the currently remaining suspects in 'gitk'. `visualize` is a bit

102 -too long to type and `view` is provided as a synonym.

103 +to see the currently remaining suspects in 'gitk'. `view` may also

104 +be used as a synonym for `visualize`.

105

104 -If 'DISPLAY' environment variable is not set, 'git log' is used

105 -instead. You can even give command line options such as `-p` and

106 +If the 'DISPLAY' environment variable is not set, 'git log' is used

107 +instead. You can also give command line options such as `-p` and

108 `--stat`.

109

110 ------------

@@ -112,57 +114,56 @@ $ git bisect view --stat

114 Bisect log and bisect replay

115 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

116

115 -The good/bad input is logged, and

117 +The good/bad input is logged, and:

118

119 ------------

120 $ git bisect log

121 ------------

122

123 shows what you have done so far. You can truncate its output somewhere

122 -and save it in a file, and run

124 +and save it in a file, and run:

125

126 ------------

127 $ git bisect replay that-file

128 ------------

129

128 -if you find later you made a mistake telling good/bad about a

129 -revision.

130 +if you find later that you made a mistake specifying revisions as good/bad.

131

131 -Avoiding to test a commit

132 +Avoiding testing a commit

133 ~~~~~~~~~~~~~~~~~~~~~~~~~

134

134 -If in a middle of bisect session, you know what the bisect suggested

135 -to try next is not a good one to test (e.g. the change the commit

135 +If in the middle of a bisect session, you know that the next suggested

136 +revision is not a good one to test (e.g. the change the commit

137 introduces is known not to work in your environment and you know it

138 does not have anything to do with the bug you are chasing), you may

138 -want to find a near-by commit and try that instead.

139 +want to find a nearby commit and try that instead.

140

140 -It goes something like this:

141 +For example:

142

143 ------------

144 $ git bisect good/bad # previous round was good/bad.

145 Bisecting: 337 revisions left to test after this

146 $ git bisect visualize # oops, that is uninteresting.

146 -$ git reset --hard HEAD~3 # try 3 revs before what

147 +$ git reset --hard HEAD~3 # try 3 revisions before what

148 # was suggested

149 ------------

150

150 -Then compile and test the one you chose to try. After that, tell

151 -bisect what the result was as usual.

151 +Then compile and test the chosen revision. Afterwards the revision

152 +is marked as good/bad in the usual manner.

153

154 Bisect skip

155 ~~~~~~~~~~~~

156

156 -Instead of choosing by yourself a nearby commit, you may just want git

157 -to do it for you using:

157 +Instead of choosing by yourself a nearby commit, you can ask git

158 +to do it for you by issuing the command:

159

160 ------------

161 $ git bisect skip # Current version cannot be tested

162 ------------

163

164 But computing the commit to test may be slower afterwards and git may

164 -eventually not be able to tell the first bad among a bad and one or

165 -more "skip"ped commits.

165 +eventually not be able to tell the first bad commit among a bad commit

166 +and one or more skipped commits.

167

168 You can even skip a range of commits, instead of just one commit,

169 using the "'<commit1>'..'<commit2>'" notation. For example:

@@ -174,30 +175,29 @@ $ git bisect skip v2.5..v2.6

175 would mean that no commit between `v2.5` excluded and `v2.6` included

176 can be tested.

177

177 -Note that if you want to also skip the first commit of a range you can

178 -use something like:

178 +Note that if you also want to skip the first commit of the range you

179 +would issue the command:

180

181 ------------

182 $ git bisect skip v2.5 v2.5..v2.6

183 ------------

184

184 -and the commit pointed to by `v2.5` will be skipped too.

185 +and the commit pointed to by `v2.5` would also be skipped.

186

187 Cutting down bisection by giving more parameters to bisect start

188 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

189

189 -You can further cut down the number of trials if you know what part of

190 -the tree is involved in the problem you are tracking down, by giving

191 -paths parameters when you say `bisect start`, like this:

190 +You can further cut down the number of trials, if you know what part of

191 +the tree is involved in the problem you are tracking down, by specifying

192 +path parameters when issuing the `bisect start` command, like this:

193

194 ------------

195 $ git bisect start -- arch/i386 include/asm-i386

196 ------------

197

197 -If you know beforehand more than one good commits, you can narrow the

198 -bisect space down without doing the whole tree checkout every time you

199 -give good commits. You give the bad revision immediately after `start`

200 -and then you give all the good revisions you have:

198 +If you know beforehand more than one good commit, you can narrow the

199 +bisect space down by specifying all of the good commits immediately after

200 +the bad commit when issuing the `bisect start` command:

201

202 ------------

203 $ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --

@@ -209,38 +209,38 @@ Bisect run

209 ~~~~~~~~~~

210

211 If you have a script that can tell if the current source code is good

212 -or bad, you can automatically bisect using:

212 +or bad, you can bisect by issuing the command:

213

214 ------------

215 $ git bisect run my_script

216 ------------

217

218 -Note that the "run" script (`my_script` in the above example) should

219 -exit with code 0 in case the current source code is good. Exit with a

218 +Note that the script (`my_script` in the above example) should

219 +exit with code 0 if the current source code is good, and exit with a

220 code between 1 and 127 (inclusive), except 125, if the current

221 source code is bad.

222

223 -Any other exit code will abort the automatic bisect process. (A

224 -program that does "exit(-1)" leaves $? = 255, see exit(3) manual page,

225 -the value is chopped with "& 0377".)

223 +Any other exit code will abort the bisect process. It should be noted

224 +that a program that terminates via "exit(-1)" leaves $? = 255, (see the

225 +exit(3) manual page), as the value is chopped with "& 0377".

226

227 The special exit code 125 should be used when the current source code

228 -cannot be tested. If the "run" script exits with this code, the current

229 -revision will be skipped, see `git bisect skip` above.

228 +cannot be tested. If the script exits with this code, the current

229 +revision will be skipped (see `git bisect skip` above).

230

231 -You may often find that during bisect you want to have near-constant

232 -tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or

233 -"revision that does not have this commit needs this patch applied to

234 -work around other problem this bisection is not interested in")

235 -applied to the revision being tested.

231 +You may often find that during a bisect session you want to have

232 +temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a

233 +header file, or "revision that does not have this commit needs this

234 +patch applied to work around another problem this bisection is not

235 +interested in") applied to the revision being tested.

236

237 To cope with such a situation, after the inner 'git bisect' finds the

238 -next revision to test, with the "run" script, you can apply that tweak

239 -before compiling, run the real test, and after the test decides if the

240 -revision (possibly with the needed tweaks) passed the test, rewind the

241 -tree to the pristine state. Finally the "run" script can exit with

242 -the status of the real test to let the "git bisect run" command loop to

243 -determine the outcome.

238 +next revision to test, the script can apply the patch

239 +before compiling, run the real test, and afterwards decide if the

240 +revision (possibly with the needed patch) passed the test and then

241 +rewind the tree to the pristine state. Finally the script should exit

242 +with the status of the real test to let the "git bisect run" command loop

243 +to determine the eventual outcome of the bisect session.

244

245 EXAMPLES

246 --------

@@ -257,39 +257,39 @@ $ git bisect run make # "make" builds the app

257 ------------

258 $ cat ~/test.sh

259 #!/bin/sh

260 -make || exit 125 # this "skip"s broken builds

260 +make || exit 125 # this skips broken builds

261 make test # "make test" runs the test suite

262 $ git bisect start v1.3 v1.1 -- # v1.3 is bad, v1.1 is good

263 $ git bisect run ~/test.sh

264 ------------

265 +

266 Here we use a "test.sh" custom script. In this script, if "make"

267 -fails, we "skip" the current commit.

267 +fails, we skip the current commit.

268 +

269 -It's safer to use a custom script outside the repo to prevent

269 +It is safer to use a custom script outside the repository to prevent

270 interactions between the bisect, make and test processes and the

271 script.

272 +

273 -And "make test" should "exit 0", if the test suite passes, and

274 -"exit 1" (for example) otherwise.

273 +"make test" should "exit 0", if the test suite passes, and

274 +"exit 1" otherwise.

275

276 * Automatically bisect a broken test case:

277 +

278 ------------

279 $ cat ~/test.sh

280 #!/bin/sh

281 -make || exit 125 # this "skip"s broken builds

281 +make || exit 125 # this skips broken builds

282 ~/check_test_case.sh # does the test case passes ?

283 $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10

284 $ git bisect run ~/test.sh

285 ------------

286 +

287 -Here "check_test_case.sh" should "exit 0", if the test case passes,

288 -and "exit 1" (for example) otherwise.

287 +Here "check_test_case.sh" should "exit 0" if the test case passes,

288 +and "exit 1" otherwise.

289 +

290 -It's safer if both "test.sh" and "check_test_case.sh" scripts are

291 -outside the repo to prevent interactions between the bisect, make and

292 -test processes and the scripts.

290 +It is safer if both "test.sh" and "check_test_case.sh" scripts are

291 +outside the repository to prevent interactions between the bisect,

292 +make and test processes and the scripts.

293

294 Author

295 ------

Documentation: reword the "Description" section of git-bisect.txt.