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>
This commit is contained in:
Jeff King 2011-08-03 20:13:29 -06:00 committed by Junio C Hamano
parent 927cd1fc94
commit 5d2fc9135a
13 changed files with 66 additions and 66 deletions

View File

@ -142,41 +142,41 @@ while archiving any tree in your `$GIT_DIR/info/attributes` file.
EXAMPLES EXAMPLES
-------- --------
git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -):: `git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)`::
Create a tar archive that contains the contents of the Create a tar archive that contains the contents of the
latest commit on the current branch, and extract it in the latest commit on the current branch, and extract it in the
`/var/tmp/junk` directory. `/var/tmp/junk` directory.
git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz:: `git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz`::
Create a compressed tarball for v1.4.0 release. Create a compressed tarball for v1.4.0 release.
git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz:: `git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz`::
Same as above, but using the builtin tar.gz handling. Same as above, but using the builtin tar.gz handling.
git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0:: `git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0`::
Same as above, but the format is inferred from the output file. Same as above, but the format is inferred from the output file.
git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz:: `git archive --format=tar --prefix=git-1.4.0/ v1.4.0{caret}\{tree\} | gzip >git-1.4.0.tar.gz`::
Create a compressed tarball for v1.4.0 release, but without a Create a compressed tarball for v1.4.0 release, but without a
global extended pax header. global extended pax header.
git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip:: `git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip`::
Put everything in the current head's Documentation/ directory Put everything in the current head's Documentation/ directory
into 'git-1.4.0-docs.zip', with the prefix 'git-docs/'. into 'git-1.4.0-docs.zip', with the prefix 'git-docs/'.
git archive -o latest.zip HEAD:: `git archive -o latest.zip HEAD`::
Create a Zip archive that contains the contents of the latest Create a Zip archive that contains the contents of the latest
commit on the current branch. Note that the output format is commit on the current branch. Note that the output format is
inferred by the extension of the output file. inferred by the extension of the output file.
git config tar.tar.xz.command "xz -c":: `git config tar.tar.xz.command "xz -c"`::
Configure a "tar.xz" format for making LZMA-compressed tarfiles. Configure a "tar.xz" format for making LZMA-compressed tarfiles.
You can use it specifying `--format=tar.xz`, or by creating an You can use it specifying `--format=tar.xz`, or by creating an

View File

@ -112,31 +112,31 @@ effect to your index in a row.
EXAMPLES EXAMPLES
-------- --------
git cherry-pick master:: `git cherry-pick master`::
Apply the change introduced by the commit at the tip of the Apply the change introduced by the commit at the tip of the
master branch and create a new commit with this change. master branch and create a new commit with this change.
git cherry-pick ..master:: `git cherry-pick ..master`::
git cherry-pick ^HEAD master:: `git cherry-pick ^HEAD master`::
Apply the changes introduced by all commits that are ancestors Apply the changes introduced by all commits that are ancestors
of master but not of HEAD to produce new commits. of master but not of HEAD to produce new commits.
git cherry-pick master{tilde}4 master{tilde}2:: `git cherry-pick master{tilde}4 master{tilde}2`::
Apply the changes introduced by the fifth and third last Apply the changes introduced by the fifth and third last
commits pointed to by master and create 2 new commits with commits pointed to by master and create 2 new commits with
these changes. these changes.
git cherry-pick -n master~1 next:: `git cherry-pick -n master~1 next`::
Apply to the working tree and the index the changes introduced Apply to the working tree and the index the changes introduced
by the second last commit pointed to by master and by the last by the second last commit pointed to by master and by the last
commit pointed to by next, but do not create any commit with commit pointed to by next, but do not create any commit with
these changes. these changes.
git cherry-pick --ff ..next:: `git cherry-pick --ff ..next`::
If history is linear and HEAD is an ancestor of next, update If history is linear and HEAD is an ancestor of next, update
the working tree and advance the HEAD pointer to match next. the working tree and advance the HEAD pointer to match next.
@ -144,7 +144,7 @@ git cherry-pick --ff ..next::
are in next but not HEAD to the current branch, creating a new are in next but not HEAD to the current branch, creating a new
commit for each new change. commit for each new change.
git rev-list --reverse master \-- README | git cherry-pick -n --stdin:: `git rev-list --reverse master \-- README | git cherry-pick -n --stdin`::
Apply the changes introduced by all commits on the master Apply the changes introduced by all commits on the master
branch that touched README to the working tree and index, branch that touched README to the working tree and index,

View File

@ -215,15 +215,15 @@ OPTIONS
Examples Examples
-------- --------
git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}:: `git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}`::
Looks for `time_t` in all tracked .c and .h files in the working Looks for `time_t` in all tracked .c and .h files in the working
directory and its subdirectories. directory and its subdirectories.
git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \):: `git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \)`::
Looks for a line that has `#define` and either `MAX_PATH` or Looks for a line that has `#define` and either `MAX_PATH` or
`PATH_MAX`. `PATH_MAX`.
git grep --all-match -e NODE -e Unexpected:: `git grep --all-match -e NODE -e Unexpected`::
Looks for a line that has `NODE` or `Unexpected` in Looks for a line that has `NODE` or `Unexpected` in
files that have lines that match both. files that have lines that match both.

View File

@ -50,7 +50,7 @@ version::
Examples Examples
-------- --------
git gui blame Makefile:: `git gui blame Makefile`::
Show the contents of the file 'Makefile' in the current Show the contents of the file 'Makefile' in the current
working directory, and provide annotations for both the working directory, and provide annotations for both the
@ -59,41 +59,41 @@ git gui blame Makefile::
uncommitted changes (if any) are explicitly attributed to uncommitted changes (if any) are explicitly attributed to
'Not Yet Committed'. 'Not Yet Committed'.
git gui blame v0.99.8 Makefile:: `git gui blame v0.99.8 Makefile`::
Show the contents of 'Makefile' in revision 'v0.99.8' Show the contents of 'Makefile' in revision 'v0.99.8'
and provide annotations for each line. Unlike the above and provide annotations for each line. Unlike the above
example the file is read from the object database and not example the file is read from the object database and not
the working directory. the working directory.
git gui blame --line=100 Makefile:: `git gui blame --line=100 Makefile`::
Loads annotations as described above and automatically Loads annotations as described above and automatically
scrolls the view to center on line '100'. scrolls the view to center on line '100'.
git gui citool:: `git gui citool`::
Make one commit and return to the shell when it is complete. Make one commit and return to the shell when it is complete.
This command returns a non-zero exit code if the window was This command returns a non-zero exit code if the window was
closed in any way other than by making a commit. closed in any way other than by making a commit.
git gui citool --amend:: `git gui citool --amend`::
Automatically enter the 'Amend Last Commit' mode of Automatically enter the 'Amend Last Commit' mode of
the interface. the interface.
git gui citool --nocommit:: `git gui citool --nocommit`::
Behave as normal citool, but instead of making a commit Behave as normal citool, but instead of making a commit
simply terminate with a zero exit code. It still checks simply terminate with a zero exit code. It still checks
that the index does not contain any unmerged entries, so that the index does not contain any unmerged entries, so
you can use it as a GUI version of linkgit:git-mergetool[1] you can use it as a GUI version of linkgit:git-mergetool[1]
git citool:: `git citool`::
Same as `git gui citool` (above). Same as `git gui citool` (above).
git gui browser maint:: `git gui browser maint`::
Show a browser for the tree of the 'maint' branch. Files Show a browser for the tree of the 'maint' branch. Files
selected in the browser can be viewed with the internal selected in the browser can be viewed with the internal

View File

@ -88,45 +88,45 @@ include::diff-generate-patch.txt[]
Examples Examples
-------- --------
git log --no-merges:: `git log --no-merges`::
Show the whole commit history, but skip any merges Show the whole commit history, but skip any merges
git log v2.6.12.. include/scsi drivers/scsi:: `git log v2.6.12.. include/scsi drivers/scsi`::
Show all commits since version 'v2.6.12' that changed any file Show all commits since version 'v2.6.12' that changed any file
in the include/scsi or drivers/scsi subdirectories in the include/scsi or drivers/scsi subdirectories
git log --since="2 weeks ago" \-- gitk:: `git log --since="2 weeks ago" \-- gitk`::
Show the changes during the last two weeks to the file 'gitk'. Show the changes during the last two weeks to the file 'gitk'.
The "--" is necessary to avoid confusion with the *branch* named The "--" is necessary to avoid confusion with the *branch* named
'gitk' 'gitk'
git log --name-status release..test:: `git log --name-status release..test`::
Show the commits that are in the "test" branch but not yet Show the commits that are in the "test" branch but not yet
in the "release" branch, along with the list of paths in the "release" branch, along with the list of paths
each commit modifies. each commit modifies.
git log --follow builtin-rev-list.c:: `git log --follow builtin-rev-list.c`::
Shows the commits that changed builtin-rev-list.c, including Shows the commits that changed builtin-rev-list.c, including
those commits that occurred before the file was given its those commits that occurred before the file was given its
present name. present name.
git log --branches --not --remotes=origin:: `git log --branches --not --remotes=origin`::
Shows all commits that are in any of local branches but not in Shows all commits that are in any of local branches but not in
any of remote-tracking branches for 'origin' (what you have that any of remote-tracking branches for 'origin' (what you have that
origin doesn't). origin doesn't).
git log master --not --remotes=*/master:: `git log master --not --remotes=*/master`::
Shows all commits that are in local master but not in any remote Shows all commits that are in local master but not in any remote
repository master branches. repository master branches.
git log -p -m --first-parent:: `git log -p -m --first-parent`::
Shows the history including change diffs, but only from the Shows the history including change diffs, but only from the
"main branch" perspective, skipping commits that come from merged "main branch" perspective, skipping commits that come from merged

View File

@ -76,12 +76,12 @@ OPTIONS
EXAMPLES EXAMPLES
-------- --------
git merge-file README.my README README.upstream:: `git merge-file README.my README README.upstream`::
combines the changes of README.my and README.upstream since README, combines the changes of README.my and README.upstream since README,
tries to merge them and writes the result into README.my. tries to merge them and writes the result into README.my.
git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345:: `git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345`::
merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels
`a` and `c` instead of `tmp/a123` and `tmp/c345`. `a` and `c` instead of `tmp/a123` and `tmp/c345`.

View File

@ -327,12 +327,12 @@ a case where you do mean to lose history.
Examples Examples
-------- --------
git push:: `git push`::
Works like `git push <remote>`, where <remote> is the Works like `git push <remote>`, where <remote> is the
current branch's remote (or `origin`, if no remote is current branch's remote (or `origin`, if no remote is
configured for the current branch). configured for the current branch).
git push origin:: `git push origin`::
Without additional configuration, works like Without additional configuration, works like
`git push origin :`. `git push origin :`.
+ +
@ -344,45 +344,45 @@ use `git config remote.origin.push HEAD`. Any valid <refspec> (like
the ones in the examples below) can be configured as the default for the ones in the examples below) can be configured as the default for
`git push origin`. `git push origin`.
git push origin ::: `git push origin :`::
Push "matching" branches to `origin`. See Push "matching" branches to `origin`. See
<refspec> in the <<OPTIONS,OPTIONS>> section above for a <refspec> in the <<OPTIONS,OPTIONS>> section above for a
description of "matching" branches. description of "matching" branches.
git push origin master:: `git push origin master`::
Find a ref that matches `master` in the source repository Find a ref that matches `master` in the source repository
(most likely, it would find `refs/heads/master`), and update (most likely, it would find `refs/heads/master`), and update
the same ref (e.g. `refs/heads/master`) in `origin` repository the same ref (e.g. `refs/heads/master`) in `origin` repository
with it. If `master` did not exist remotely, it would be with it. If `master` did not exist remotely, it would be
created. created.
git push origin HEAD:: `git push origin HEAD`::
A handy way to push the current branch to the same name on the A handy way to push the current branch to the same name on the
remote. remote.
git push origin master:satellite/master dev:satellite/dev:: `git push origin master:satellite/master dev:satellite/dev`::
Use the source ref that matches `master` (e.g. `refs/heads/master`) Use the source ref that matches `master` (e.g. `refs/heads/master`)
to update the ref that matches `satellite/master` (most probably to update the ref that matches `satellite/master` (most probably
`refs/remotes/satellite/master`) in the `origin` repository, then `refs/remotes/satellite/master`) in the `origin` repository, then
do the same for `dev` and `satellite/dev`. do the same for `dev` and `satellite/dev`.
git push origin HEAD:master:: `git push origin HEAD:master`::
Push the current branch to the remote ref matching `master` in the Push the current branch to the remote ref matching `master` in the
`origin` repository. This form is convenient to push the current `origin` repository. This form is convenient to push the current
branch without thinking about its local name. branch without thinking about its local name.
git push origin master:refs/heads/experimental:: `git push origin master:refs/heads/experimental`::
Create the branch `experimental` in the `origin` repository Create the branch `experimental` in the `origin` repository
by copying the current `master` branch. This form is only by copying the current `master` branch. This form is only
needed to create a new branch or tag in the remote repository when needed to create a new branch or tag in the remote repository when
the local name and the remote name are different; otherwise, the local name and the remote name are different; otherwise,
the ref name on its own will work. the ref name on its own will work.
git push origin :experimental:: `git push origin :experimental`::
Find a ref that matches `experimental` in the `origin` repository Find a ref that matches `experimental` in the `origin` repository
(e.g. `refs/heads/experimental`), and delete it. (e.g. `refs/heads/experimental`), and delete it.
git push origin {plus}dev:master:: `git push origin {plus}dev:master`::
Update the origin repository's master branch with the dev branch, Update the origin repository's master branch with the dev branch,
allowing non-fast-forward updates. *This can leave unreferenced allowing non-fast-forward updates. *This can leave unreferenced
commits dangling in the origin repository.* Consider the commits dangling in the origin repository.* Consider the

View File

@ -35,19 +35,19 @@ GIT_TRANSLOOP_DEBUG::
EXAMPLES EXAMPLES
-------- --------
git fetch fd::17 master:: `git fetch fd::17 master`::
Fetch master, using file descriptor #17 to communicate with Fetch master, using file descriptor #17 to communicate with
git-upload-pack. git-upload-pack.
git fetch fd::17/foo master:: `git fetch fd::17/foo master`::
Same as above. Same as above.
git push fd::7,8 master (as URL):: `git push fd::7,8 master (as URL)`::
Push master, using file descriptor #7 to read data from Push master, using file descriptor #7 to read data from
git-receive-pack and file descriptor #8 to write data to git-receive-pack and file descriptor #8 to write data to
same service. same service.
git push fd::7,8/bar master:: `git push fd::7,8/bar master`::
Same as above. Same as above.
Documentation Documentation

View File

@ -93,12 +93,12 @@ effect to your index in a row.
EXAMPLES EXAMPLES
-------- --------
git revert HEAD~3:: `git revert HEAD~3`::
Revert the changes specified by the fourth last commit in HEAD Revert the changes specified by the fourth last commit in HEAD
and create a new commit with the reverted changes. and create a new commit with the reverted changes.
git revert -n master{tilde}5..master{tilde}2:: `git revert -n master{tilde}5..master{tilde}2`::
Revert the changes done by commits from the fifth last commit Revert the changes done by commits from the fifth last commit
in master (included) to the third last commit in master in master (included) to the third last commit in master

View File

@ -137,7 +137,7 @@ git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached
EXAMPLES EXAMPLES
-------- --------
git rm Documentation/\*.txt:: `git rm Documentation/\*.txt`::
Removes all `*.txt` files from the index that are under the Removes all `*.txt` files from the index that are under the
`Documentation` directory and any of its subdirectories. `Documentation` directory and any of its subdirectories.
+ +
@ -145,7 +145,7 @@ Note that the asterisk `*` is quoted from the shell in this
example; this lets git, and not the shell, expand the pathnames example; this lets git, and not the shell, expand the pathnames
of files and subdirectories under the `Documentation/` directory. of files and subdirectories under the `Documentation/` directory.
git rm -f git-*.sh:: `git rm -f git-*.sh`::
Because this example lets the shell expand the asterisk Because this example lets the shell expand the asterisk
(i.e. you are listing the files explicitly), it (i.e. you are listing the files explicitly), it
does not remove `subdir/git-foo.sh`. does not remove `subdir/git-foo.sh`.

View File

@ -48,23 +48,23 @@ include::pretty-formats.txt[]
EXAMPLES EXAMPLES
-------- --------
git show v1.0.0:: `git show v1.0.0`::
Shows the tag `v1.0.0`, along with the object the tags Shows the tag `v1.0.0`, along with the object the tags
points at. points at.
git show v1.0.0^\{tree\}:: `git show v1.0.0^\{tree\}`::
Shows the tree pointed to by the tag `v1.0.0`. Shows the tree pointed to by the tag `v1.0.0`.
git show -s --format=%s v1.0.0^\{commit\}:: `git show -s --format=%s v1.0.0^\{commit\}`::
Shows the subject of the commit pointed to by the Shows the subject of the commit pointed to by the
tag `v1.0.0`. tag `v1.0.0`.
git show next~10:Documentation/README:: `git show next~10:Documentation/README`::
Shows the contents of the file `Documentation/README` as Shows the contents of the file `Documentation/README` as
they were current in the 10th last commit of the branch they were current in the 10th last commit of the branch
`next`. `next`.
git show master:Makefile master:t/Makefile:: `git show master:Makefile master:t/Makefile`::
Concatenates the contents of said Makefiles in the head Concatenates the contents of said Makefiles in the head
of the branch `master`. of the branch `master`.

View File

@ -53,26 +53,26 @@ tar.umask::
EXAMPLES EXAMPLES
-------- --------
git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -):: `git tar-tree HEAD junk | (cd /var/tmp/ && tar xf -)`::
Create a tar archive that contains the contents of the Create a tar archive that contains the contents of the
latest commit on the current branch, and extracts it in latest commit on the current branch, and extracts it in
`/var/tmp/junk` directory. `/var/tmp/junk` directory.
git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz:: `git tar-tree v1.4.0 git-1.4.0 | gzip >git-1.4.0.tar.gz`::
Create a tarball for v1.4.0 release. Create a tarball for v1.4.0 release.
git tar-tree v1.4.0{caret}\{tree\} git-1.4.0 | gzip >git-1.4.0.tar.gz:: `git tar-tree v1.4.0{caret}\{tree\} git-1.4.0 | gzip >git-1.4.0.tar.gz`::
Create a tarball for v1.4.0 release, but without a Create a tarball for v1.4.0 release, but without a
global extended pax header. global extended pax header.
git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar:: `git tar-tree --remote=example.com:git.git v1.4.0 >git-1.4.0.tar`::
Get a tarball v1.4.0 from example.com. Get a tarball v1.4.0 from example.com.
git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar:: `git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar`::
Put everything in the current head's Documentation/ directory Put everything in the current head's Documentation/ directory
into 'git-1.4.0-docs.tar', with the prefix 'git-docs/'. into 'git-1.4.0-docs.tar', with the prefix 'git-docs/'.

View File

@ -53,12 +53,12 @@ include::pretty-formats.txt[]
Examples Examples
-------- --------
git whatchanged -p v2.6.12.. include/scsi drivers/scsi:: `git whatchanged -p v2.6.12.. include/scsi drivers/scsi`::
Show as patches the commits since version 'v2.6.12' that changed Show as patches the commits since version 'v2.6.12' that changed
any file in the include/scsi or drivers/scsi subdirectories any file in the include/scsi or drivers/scsi subdirectories
git whatchanged --since="2 weeks ago" \-- gitk:: `git whatchanged --since="2 weeks ago" \-- gitk`::
Show the changes during the last two weeks to the file 'gitk'. Show the changes during the last two weeks to the file 'gitk'.
The "--" is necessary to avoid confusion with the *branch* named The "--" is necessary to avoid confusion with the *branch* named