Skip to content

Commit 88f78ce

Browse files
gitstergitster
committed
Merge branch 'dm/maint-docco'
* dm/maint-docco: Documentation: reword example text in git-bisect.txt. Documentation: reworded the "Description" section of git-bisect.txt. Documentation: minor grammatical fixes in git-branch.txt. Documentation: minor grammatical fixes in git-blame.txt. Documentation: reword the "Description" section of git-bisect.txt. Documentation: minor grammatical fixes in git-archive.txt.
2 parents d291a9a + 4306bcb commit 88f78ce

File tree

6 files changed

+154
-150
lines changed

6 files changed

+154
-150
lines changed

‎Documentation/blame-options.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ of lines before or after the line given by <start>.
3939
Show raw timestamp (Default: off).
4040

4141
-S <revs-file>::
42-
Use revs from revs-file instead of calling linkgit:git-rev-list[1].
42+
Use revisions from revs-file instead of calling linkgit:git-rev-list[1].
4343

4444
--reverse::
4545
Walk history forward instead of backward. Instead of showing

‎Documentation/git-archive.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ prepended to the filenames in the archive.
2323

2424
'git-archive' behaves differently when given a tree ID versus when
2525
given a commit ID or tag ID. In the first case the current time is
26-
used as modification time of each file in the archive. In the latter
26+
used as the modification time of each file in the archive. In the latter
2727
case the commit time as recorded in the referenced commit object is
2828
used instead. Additionally the commit ID is stored in a global
2929
extended pax header if the tar format is used; it can be extracted
@@ -52,11 +52,11 @@ OPTIONS
5252
Write the archive to <file> instead of stdout.
5353

5454
<extra>::
55-
This can be any options that the archiver backend understand.
55+
This can be any options that the archiver backend understands.
5656
See next section.
5757

5858
--remote=<repo>::
59-
Instead of making a tar archive from local repository,
59+
Instead of making a tar archive from the local repository,
6060
retrieve a tar archive from a remote repository.
6161

6262
--exec=<git-upload-archive>::
@@ -109,7 +109,7 @@ EXAMPLES
109109
git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)::
110110

111111
Create a tar archive that contains the contents of the
112-
latest commit on the current branch, and extracts it in
112+
latest commit on the current branch, and extract it in the
113113
`/var/tmp/junk` directory.
114114

115115
git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz::

‎Documentation/git-bisect.txt‎

Lines changed: 88 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ git-bisect(1)
33

44
NAME
55
----
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
77

88

99
SYNOPSIS
@@ -39,7 +39,8 @@ help" or "git bisect -h" to get a long usage description.
3939
Basic bisect commands: start, bad, good
4040
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4141

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:
4344

4445
------------------------------------------------
4546
$ git bisect start
@@ -48,61 +49,63 @@ $ git bisect good v2.6.13-rc2 # v2.6.13-rc2 was the last version
4849
# tested that was good
4950
------------------------------------------------
5051

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+
the following:
5355

5456
------------------------------------------------
5557
Bisecting: 675 revisions left to test after this
5658
------------------------------------------------
5759

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
60+
The state in the middle of the set of revisions is then checked out.
61+
You would now compile that kernel and boot it. If the booted kernel
62+
works correctly, you would then issue the following command:
6163

6264
------------------------------------------------
6365
$ git bisect good # this one is good
6466
------------------------------------------------
6567

66-
which will now say
68+
The output of this command would be something similar to the following:
6769

6870
------------------------------------------------
6971
Bisecting: 337 revisions left to test after this
7072
------------------------------------------------
7173

72-
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+
You keep repeating this process, compiling the tree, testing it, and
75+
depending on whether it is good or bad issuing the command "git bisect good"
76+
or "git bisect bad" to ask for the next bisection.
7577

76-
Until you have no more left, and you'll have been left with the first
77-
bad kernel rev in "refs/bisect/bad".
78+
Eventually there will be no more revisions left to bisect, and you
79+
will have been left with the first bad kernel revision in "refs/bisect/bad".
7880

7981
Bisect reset
8082
~~~~~~~~~~~~
8183

82-
Oh, and then after you want to reset to the original head, do a
84+
To return to the original head after a bisect session, you issue the
85+
following command:
8386

8487
------------------------------------------------
8588
$ git bisect reset
8689
------------------------------------------------
8790

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).
91+
This resets the tree to the original branch instead of being on the
92+
bisection commit ("git bisect start" will also do that, as it resets
93+
the bisection state).
9194

9295
Bisect visualize
9396
~~~~~~~~~~~~~~~~
9497

95-
During the bisection process, you can say
98+
To see the currently remaining suspects in 'gitk', the following command
99+
is issued during the bisection process:
96100

97101
------------
98102
$ git bisect visualize
99103
------------
100104

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.
105+
`view` may also be used as a synonym for `visualize`.
103106

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
107+
If the 'DISPLAY' environment variable is not set, 'git log' is used
108+
instead. You can also give command line options such as `-p` and
106109
`--stat`.
107110

108111
------------
@@ -112,57 +115,58 @@ $ git bisect view --stat
112115
Bisect log and bisect replay
113116
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
114117

115-
The good/bad input is logged, and
118+
After having marked revisions as good or bad, you issue the following
119+
command to show what has been done so far:
116120

117121
------------
118122
$ git bisect log
119123
------------
120124

121-
shows what you have done so far. You can truncate its output somewhere
122-
and save it in a file, and run
125+
If you discover that you made a mistake in specifying the status of a
126+
revision, you can save the output of this command to a file, edit it to
127+
remove the incorrect entries, and then issue the following commands to
128+
return to a corrected state:
123129

124130
------------
131+
$ git bisect reset
125132
$ git bisect replay that-file
126133
------------
127134

128-
if you find later you made a mistake telling good/bad about a
129-
revision.
130-
131-
Avoiding to test a commit
135+
Avoiding testing a commit
132136
~~~~~~~~~~~~~~~~~~~~~~~~~
133137

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
138+
If in the middle of a bisect session, you know that the next suggested
139+
revision is not a good one to test (e.g. the change the commit
136140
introduces is known not to work in your environment and you know it
137141
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.
142+
want to find a nearby commit and try that instead.
139143

140-
It goes something like this:
144+
For example:
141145

142146
------------
143-
$ git bisect good/bad # previous round was good/bad.
147+
$ git bisect good/bad # previous round was good or bad.
144148
Bisecting: 337 revisions left to test after this
145149
$ git bisect visualize # oops, that is uninteresting.
146-
$ git reset --hard HEAD~3 # try 3 revs before what
150+
$ git reset --hard HEAD~3 # try 3 revisions before what
147151
# was suggested
148152
------------
149153

150-
Then compile and test the one you chose to try. After that, tell
151-
bisect what the result was as usual.
154+
Then compile and test the chosen revision. Afterwards the revision
155+
is marked as good or bad in the usual manner.
152156

153157
Bisect skip
154158
~~~~~~~~~~~~
155159

156-
Instead of choosing by yourself a nearby commit, you may just want git
157-
to do it for you using:
160+
Instead of choosing by yourself a nearby commit, you can ask git
161+
to do it for you by issuing the command:
158162

159163
------------
160164
$ git bisect skip # Current version cannot be tested
161165
------------
162166

163167
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.
168+
eventually not be able to tell the first bad commit among a bad commit
169+
and one or more skipped commits.
166170

167171
You can even skip a range of commits, instead of just one commit,
168172
using the "'<commit1>'..'<commit2>'" notation. For example:
@@ -171,33 +175,34 @@ using the "'<commit1>'..'<commit2>'" notation. For example:
171175
$ git bisect skip v2.5..v2.6
172176
------------
173177

174-
would mean that no commit between `v2.5` excluded and `v2.6` included
175-
can be tested.
178+
The effect of this would be that no commit between `v2.5` excluded and
179+
`v2.6` included could be tested.
176180

177-
Note that if you want to also skip the first commit of a range you can
178-
use something like:
181+
Note that if you also want to skip the first commit of the range you
182+
would issue the command:
179183

180184
------------
181185
$ git bisect skip v2.5 v2.5..v2.6
182186
------------
183187

184-
and the commit pointed to by `v2.5` will be skipped too.
188+
This would cause the commits between `v2.5` included and `v2.6` included
189+
to be skipped.
190+
185191

186192
Cutting down bisection by giving more parameters to bisect start
187193
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188194

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:
195+
You can further cut down the number of trials, if you know what part of
196+
the tree is involved in the problem you are tracking down, by specifying
197+
path parameters when issuing the `bisect start` command:
192198

193199
------------
194200
$ git bisect start -- arch/i386 include/asm-i386
195201
------------
196202

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:
203+
If you know beforehand more than one good commit, you can narrow the
204+
bisect space down by specifying all of the good commits immediately after
205+
the bad commit when issuing the `bisect start` command:
201206

202207
------------
203208
$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
@@ -209,38 +214,38 @@ Bisect run
209214
~~~~~~~~~~
210215

211216
If you have a script that can tell if the current source code is good
212-
or bad, you can automatically bisect using:
217+
or bad, you can bisect by issuing the command:
213218

214219
------------
215220
$ git bisect run my_script arguments
216221
------------
217222

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
223+
Note that the script (`my_script` in the above example) should
224+
exit with code 0 if the current source code is good, and exit with a
220225
code between 1 and 127 (inclusive), except 125, if the current
221226
source code is bad.
222227

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".)
228+
Any other exit code will abort the bisect process. It should be noted
229+
that a program that terminates via "exit(-1)" leaves $? = 255, (see the
230+
exit(3) manual page), as the value is chopped with "& 0377".
226231

227232
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.
233+
cannot be tested. If the script exits with this code, the current
234+
revision will be skipped (see `git bisect skip` above).
230235

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.
236+
You may often find that during a bisect session you want to have
237+
temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a
238+
header file, or "revision that does not have this commit needs this
239+
patch applied to work around another problem this bisection is not
240+
interested in") applied to the revision being tested.
236241

237242
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.
243+
next revision to test, the script can apply the patch
244+
before compiling, run the real test, and afterwards decide if the
245+
revision (possibly with the needed patch) passed the test and then
246+
rewind the tree to the pristine state. Finally the script should exit
247+
with the status of the real test to let the "git bisect run" command loop
248+
determine the eventual outcome of the bisect session.
244249

245250
EXAMPLES
246251
--------
@@ -264,39 +269,39 @@ $ git bisect run make test # "make test" builds and tests
264269
------------
265270
$ cat ~/test.sh
266271
#!/bin/sh
267-
make || exit 125 # this "skip"s broken builds
272+
make || exit 125 # this skips broken builds
268273
make test # "make test" runs the test suite
269274
$ git bisect start v1.3 v1.1 -- # v1.3 is bad, v1.1 is good
270275
$ git bisect run ~/test.sh
271276
------------
272277
+
273278
Here we use a "test.sh" custom script. In this script, if "make"
274-
fails, we "skip" the current commit.
279+
fails, we skip the current commit.
275280
+
276-
It's safer to use a custom script outside the repo to prevent
281+
It is safer to use a custom script outside the repository to prevent
277282
interactions between the bisect, make and test processes and the
278283
script.
279284
+
280-
And "make test" should "exit 0", if the test suite passes, and
281-
"exit 1" (for example) otherwise.
285+
"make test" should "exit 0", if the test suite passes, and
286+
"exit 1" otherwise.
282287

283288
* Automatically bisect a broken test case:
284289
+
285290
------------
286291
$ cat ~/test.sh
287292
#!/bin/sh
288-
make || exit 125 # this "skip"s broken builds
293+
make || exit 125 # this skips broken builds
289294
~/check_test_case.sh # does the test case passes ?
290295
$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10
291296
$ git bisect run ~/test.sh
292297
------------
293298
+
294-
Here "check_test_case.sh" should "exit 0", if the test case passes,
295-
and "exit 1" (for example) otherwise.
299+
Here "check_test_case.sh" should "exit 0" if the test case passes,
300+
and "exit 1" otherwise.
296301
+
297-
It's safer if both "test.sh" and "check_test_case.sh" scripts are
298-
outside the repo to prevent interactions between the bisect, make and
299-
test processes and the scripts.
302+
It is safer if both "test.sh" and "check_test_case.sh" scripts are
303+
outside the repository to prevent interactions between the bisect,
304+
make and test processes and the scripts.
300305

301306
* Automatically bisect a broken test suite:
302307
+

0 commit comments

Comments
 (0)