@matheusbsbs / matheus-bagliano / commits / 5d2fc9135a

docs: put listed example commands in backticks

Many examples of git command invocation are given in asciidoc listing blocks, which makes them monospaced and avoids further interpretation of special characters. Some manpages make a list of examples, like: git foo:: Run git foo. git foo -q:: Use the "-q" option. to quickly show many variants. However, they can sometimes be hard to read, because they are shown in a proportional-width font (so, for example, seeing the difference between "-- foo" and "--foo" can be difficult). This patch puts all such examples into backticks, which gives the equivalent formatting to a listing block (i.e., monospaced and without character interpretation). As a bonus, this also fixes an example in the git-push manpage, in which "git push origin :::" was accidentally considered a newly-indented list, and not a list item with "git push origin :" in it. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Jeff King committed Aug 3, 2011 at 20:13 UTC 5d2fc9135a35284176e99708b9b6f32c9e6eb7a2

13 files changed +66 -66

Documentation/git-archive.txt

+8 -8

@@ -142,41 +142,41 @@ while archiving any tree in your `$GIT_DIR/info/attributes` file.

142

143 EXAMPLES

144 --------

145 -git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)::

145 +`git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)`::

146

147 Create a tar archive that contains the contents of the

148 latest commit on the current branch, and extract it in the

149 `/var/tmp/junk` directory.

150

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

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

152

153 Create a compressed tarball for v1.4.0 release.

154

155 -git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz::

155 +`git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz`::

156

157 Same as above, but using the builtin tar.gz handling.

158

159 -git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0::

159 +`git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0`::

160

161 Same as above, but the format is inferred from the output file.

162

163 -git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz::

163 +`git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz`::

164

165 Create a compressed tarball for v1.4.0 release, but without a

166 global extended pax header.

167

168 -git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip::

168 +`git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip`::

169

170 Put everything in the current head's Documentation/ directory

171 into 'git-1.4.0-docs.zip', with the prefix 'git-docs/'.

172

173 -git archive -o latest.zip HEAD::

173 +`git archive -o latest.zip HEAD`::

174

175 Create a Zip archive that contains the contents of the latest

176 commit on the current branch. Note that the output format is

177 inferred by the extension of the output file.

178

179 -git config tar.tar.xz.command "xz -c"::

179 +`git config tar.tar.xz.command "xz -c"`::

180

181 Configure a "tar.xz" format for making LZMA-compressed tarfiles.

182 You can use it specifying `--format=tar.xz`, or by creating an

Documentation/git-cherry-pick.txt

+7 -7

@@ -112,31 +112,31 @@ effect to your index in a row.

112

113 EXAMPLES

114 --------

115 -git cherry-pick master::

115 +`git cherry-pick master`::

116

117 Apply the change introduced by the commit at the tip of the

118 master branch and create a new commit with this change.

119

120 -git cherry-pick ..master::

121 -git cherry-pick ^HEAD master::

120 +`git cherry-pick ..master`::

121 +`git cherry-pick ^HEAD master`::

122

123 Apply the changes introduced by all commits that are ancestors

124 of master but not of HEAD to produce new commits.

125

126 -git cherry-pick master{tilde}4 master{tilde}2::

126 +`git cherry-pick master{tilde}4 master{tilde}2`::

127

128 Apply the changes introduced by the fifth and third last

129 commits pointed to by master and create 2 new commits with

130 these changes.

131

132 -git cherry-pick -n master~1 next::

132 +`git cherry-pick -n master~1 next`::

133

134 Apply to the working tree and the index the changes introduced

135 by the second last commit pointed to by master and by the last

136 commit pointed to by next, but do not create any commit with

137 these changes.

138

139 -git cherry-pick --ff ..next::

139 +`git cherry-pick --ff ..next`::

140

141 If history is linear and HEAD is an ancestor of next, update

142 the working tree and advance the HEAD pointer to match next.

@@ -144,7 +144,7 @@ git cherry-pick --ff ..next::

144 are in next but not HEAD to the current branch, creating a new

145 commit for each new change.

146

147 -git rev-list --reverse master \-- README | git cherry-pick -n --stdin::

147 +`git rev-list --reverse master \-- README | git cherry-pick -n --stdin`::

148

149 Apply the changes introduced by all commits on the master

150 branch that touched README to the working tree and index,

Documentation/git-grep.txt

+3 -3

@@ -215,15 +215,15 @@ OPTIONS

215 Examples

216 --------

217

218 -git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}::

218 +`git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}`::

219 Looks for `time_t` in all tracked .c and .h files in the working

220 directory and its subdirectories.

221

222 -git grep -e {apostrophe}#define{apostrophe} --and $ -e MAX_PATH -e PATH_MAX $::

222 +`git grep -e {apostrophe}#define{apostrophe} --and $ -e MAX_PATH -e PATH_MAX $`::

223 Looks for a line that has `#define` and either `MAX_PATH` or

224 `PATH_MAX`.

225

226 -git grep --all-match -e NODE -e Unexpected::

226 +`git grep --all-match -e NODE -e Unexpected`::

227 Looks for a line that has `NODE` or `Unexpected` in

228 files that have lines that match both.

229

Documentation/git-gui.txt

+8 -8

@@ -50,7 +50,7 @@ version::

51 Examples

52 --------

53 -git gui blame Makefile::

53 +`git gui blame Makefile`::

55 Show the contents of the file 'Makefile' in the current

56 working directory, and provide annotations for both the

@@ -59,41 +59,41 @@ git gui blame Makefile::

59 uncommitted changes (if any) are explicitly attributed to

60 'Not Yet Committed'.

62 -git gui blame v0.99.8 Makefile::

62 +`git gui blame v0.99.8 Makefile`::

64 Show the contents of 'Makefile' in revision 'v0.99.8'

65 and provide annotations for each line. Unlike the above

66 example the file is read from the object database and not

67 the working directory.

69 -git gui blame --line=100 Makefile::

69 +`git gui blame --line=100 Makefile`::

71 Loads annotations as described above and automatically

72 scrolls the view to center on line '100'.

74 -git gui citool::

74 +`git gui citool`::

76 Make one commit and return to the shell when it is complete.

77 This command returns a non-zero exit code if the window was

78 closed in any way other than by making a commit.

80 -git gui citool --amend::

80 +`git gui citool --amend`::

82 Automatically enter the 'Amend Last Commit' mode of

83 the interface.

85 -git gui citool --nocommit::

85 +`git gui citool --nocommit`::

87 Behave as normal citool, but instead of making a commit

88 simply terminate with a zero exit code. It still checks

89 that the index does not contain any unmerged entries, so

90 you can use it as a GUI version of linkgit:git-mergetool[1]

92 -git citool::

92 +`git citool`::

94 Same as `git gui citool` (above).

96 -git gui browser maint::

96 +`git gui browser maint`::

98 Show a browser for the tree of the 'maint' branch. Files

99 selected in the browser can be viewed with the internal

Documentation/git-log.txt

+8 -8

@@ -88,45 +88,45 @@ include::diff-generate-patch.txt[]

89 Examples

90 --------

91 -git log --no-merges::

91 +`git log --no-merges`::

93 Show the whole commit history, but skip any merges

95 -git log v2.6.12.. include/scsi drivers/scsi::

95 +`git log v2.6.12.. include/scsi drivers/scsi`::

97 Show all commits since version 'v2.6.12' that changed any file

98 in the include/scsi or drivers/scsi subdirectories

100 -git log --since="2 weeks ago" \-- gitk::

100 +`git log --since="2 weeks ago" \-- gitk`::

101

102 Show the changes during the last two weeks to the file 'gitk'.

103 The "--" is necessary to avoid confusion with the *branch* named

104 'gitk'

105

106 -git log --name-status release..test::

106 +`git log --name-status release..test`::

107

108 Show the commits that are in the "test" branch but not yet

109 in the "release" branch, along with the list of paths

110 each commit modifies.

111

112 -git log --follow builtin-rev-list.c::

112 +`git log --follow builtin-rev-list.c`::

113

114 Shows the commits that changed builtin-rev-list.c, including

115 those commits that occurred before the file was given its

116 present name.

117

118 -git log --branches --not --remotes=origin::

118 +`git log --branches --not --remotes=origin`::

119

120 Shows all commits that are in any of local branches but not in

121 any of remote-tracking branches for 'origin' (what you have that

122 origin doesn't).

123

124 -git log master --not --remotes=*/master::

124 +`git log master --not --remotes=*/master`::

125

126 Shows all commits that are in local master but not in any remote

127 repository master branches.

128

129 -git log -p -m --first-parent::

129 +`git log -p -m --first-parent`::

130

131 Shows the history including change diffs, but only from the

132 "main branch" perspective, skipping commits that come from merged

Documentation/git-merge-file.txt

+2 -2

@@ -76,12 +76,12 @@ OPTIONS

76 EXAMPLES

77 --------

79 -git merge-file README.my README README.upstream::

79 +`git merge-file README.my README README.upstream`::

81 combines the changes of README.my and README.upstream since README,

82 tries to merge them and writes the result into README.my.

84 -git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345::

84 +`git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345`::

86 merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels

87 `a` and `c` instead of `tmp/a123` and `tmp/c345`.

Documentation/git-push.txt

+10 -10

@@ -327,12 +327,12 @@ a case where you do mean to lose history.

327 Examples

328 --------

329

330 -git push::

330 +`git push`::

331 Works like `git push <remote>`, where <remote> is the

332 current branch's remote (or `origin`, if no remote is

333 configured for the current branch).

334

335 -git push origin::

335 +`git push origin`::

336 Without additional configuration, works like

337 `git push origin :`.

338 +

@@ -344,45 +344,45 @@ use `git config remote.origin.push HEAD`. Any valid <refspec> (like

344 the ones in the examples below) can be configured as the default for

345 `git push origin`.

346

347 -git push origin :::

347 +`git push origin :`::

348 Push "matching" branches to `origin`. See

349 <refspec> in the <<OPTIONS,OPTIONS>> section above for a

350 description of "matching" branches.

351

352 -git push origin master::

352 +`git push origin master`::

353 Find a ref that matches `master` in the source repository

354 (most likely, it would find `refs/heads/master`), and update

355 the same ref (e.g. `refs/heads/master`) in `origin` repository

356 with it. If `master` did not exist remotely, it would be

357 created.

358

359 -git push origin HEAD::

359 +`git push origin HEAD`::

360 A handy way to push the current branch to the same name on the

361 remote.

362

363 -git push origin master:satellite/master dev:satellite/dev::

363 +`git push origin master:satellite/master dev:satellite/dev`::

364 Use the source ref that matches `master` (e.g. `refs/heads/master`)

365 to update the ref that matches `satellite/master` (most probably

366 `refs/remotes/satellite/master`) in the `origin` repository, then

367 do the same for `dev` and `satellite/dev`.

368

369 -git push origin HEAD:master::

369 +`git push origin HEAD:master`::

370 Push the current branch to the remote ref matching `master` in the

371 `origin` repository. This form is convenient to push the current

372 branch without thinking about its local name.

373

374 -git push origin master:refs/heads/experimental::

374 +`git push origin master:refs/heads/experimental`::

375 Create the branch `experimental` in the `origin` repository

376 by copying the current `master` branch. This form is only

377 needed to create a new branch or tag in the remote repository when

378 the local name and the remote name are different; otherwise,

379 the ref name on its own will work.

380

381 -git push origin :experimental::

381 +`git push origin :experimental`::

382 Find a ref that matches `experimental` in the `origin` repository

383 (e.g. `refs/heads/experimental`), and delete it.

384

385 -git push origin {plus}dev:master::

385 +`git push origin {plus}dev:master`::

386 Update the origin repository's master branch with the dev branch,

387 allowing non-fast-forward updates. *This can leave unreferenced

388 commits dangling in the origin repository.* Consider the

Documentation/git-remote-fd.txt

+4 -4

@@ -35,19 +35,19 @@ GIT_TRANSLOOP_DEBUG::

36 EXAMPLES

37 --------

38 -git fetch fd::17 master::

38 +`git fetch fd::17 master`::

39 Fetch master, using file descriptor #17 to communicate with

40 git-upload-pack.

42 -git fetch fd::17/foo master::

42 +`git fetch fd::17/foo master`::

43 Same as above.

45 -git push fd::7,8 master (as URL)::

45 +`git push fd::7,8 master (as URL)`::

46 Push master, using file descriptor #7 to read data from

47 git-receive-pack and file descriptor #8 to write data to

48 same service.

50 -git push fd::7,8/bar master::

50 +`git push fd::7,8/bar master`::

51 Same as above.

53 Documentation

Documentation/git-revert.txt

+2 -2

@@ -93,12 +93,12 @@ effect to your index in a row.

94 EXAMPLES

95 --------

96 -git revert HEAD~3::

96 +`git revert HEAD~3`::

98 Revert the changes specified by the fourth last commit in HEAD

99 and create a new commit with the reverted changes.

100

101 -git revert -n master{tilde}5..master{tilde}2::

101 +`git revert -n master{tilde}5..master{tilde}2`::

102

103 Revert the changes done by commits from the fifth last commit

104 in master (included) to the third last commit in master

Documentation/git-rm.txt

+2 -2

@@ -137,7 +137,7 @@ git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached

137

138 EXAMPLES

139 --------

140 -git rm Documentation/\*.txt::

140 +`git rm Documentation/\*.txt`::

141 Removes all `*.txt` files from the index that are under the

142 `Documentation` directory and any of its subdirectories.

143 +

@@ -145,7 +145,7 @@ Note that the asterisk `*` is quoted from the shell in this

145 example; this lets git, and not the shell, expand the pathnames

146 of files and subdirectories under the `Documentation/` directory.

147

148 -git rm -f git-*.sh::

148 +`git rm -f git-*.sh`::

149 Because this example lets the shell expand the asterisk

150 (i.e. you are listing the files explicitly), it

151 does not remove `subdir/git-foo.sh`.

Documentation/git-show.txt

+5 -5

@@ -48,23 +48,23 @@ include::pretty-formats.txt[]

48 EXAMPLES

49 --------

51 -git show v1.0.0::

51 +`git show v1.0.0`::

52 Shows the tag `v1.0.0`, along with the object the tags

53 points at.

55 -git show v1.0.0^\{tree\}::

55 +`git show v1.0.0^\{tree\}`::

56 Shows the tree pointed to by the tag `v1.0.0`.

58 -git show -s --format=%s v1.0.0^\{commit\}::

58 +`git show -s --format=%s v1.0.0^\{commit\}`::

59 Shows the subject of the commit pointed to by the

60 tag `v1.0.0`.

62 -git show next~10:Documentation/README::

62 +`git show next~10:Documentation/README`::

63 Shows the contents of the file `Documentation/README` as

64 they were current in the 10th last commit of the branch

65 `next`.

67 -git show master:Makefile master:t/Makefile::

67 +`git show master:Makefile master:t/Makefile`::

68 Concatenates the contents of said Makefiles in the head

69 of the branch `master`.

Documentation/git-tar-tree.txt

+5 -5

@@ -53,26 +53,26 @@ tar.umask::

54 EXAMPLES

55 --------

56 -git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -)::

56 +`git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -)`::

58 Create a tar archive that contains the contents of the

59 latest commit on the current branch, and extracts it in

60 `/var/tmp/junk` directory.

62 -git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz::

62 +`git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz`::

64 Create a tarball for v1.4.0 release.

66 -git tar-tree v1.4.0{caret}\{tree\} git-1.4.0 | gzip >git-1.4.0.tar.gz::

66 +`git tar-tree v1.4.0{caret}\{tree\} git-1.4.0 | gzip >git-1.4.0.tar.gz`::

68 Create a tarball for v1.4.0 release, but without a

69 global extended pax header.

71 -git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar::

71 +`git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar`::

73 Get a tarball v1.4.0 from example.com.

75 -git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar::

75 +`git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar`::

77 Put everything in the current head's Documentation/ directory

78 into 'git-1.4.0-docs.tar', with the prefix 'git-docs/'.

Documentation/git-whatchanged.txt

+2 -2

@@ -53,12 +53,12 @@ include::pretty-formats.txt[]

54 Examples

55 --------

56 -git whatchanged -p v2.6.12.. include/scsi drivers/scsi::

56 +`git whatchanged -p v2.6.12.. include/scsi drivers/scsi`::

58 Show as patches the commits since version 'v2.6.12' that changed

59 any file in the include/scsi or drivers/scsi subdirectories

61 -git whatchanged --since="2 weeks ago" \-- gitk::

61 +`git whatchanged --since="2 weeks ago" \-- gitk`::

63 Show the changes during the last two weeks to the file 'gitk'.

64 The "--" is necessary to avoid confusion with the *branch* named