Documentation formatting and cleanup

Following what appears to be the predominant style, format
names of commands and commandlines both as `teletype text`.

While we're at it, add articles ("a" and "the") in some
places, italicize the name of the command in the manual page
synopsis line, and add a comma or two where it seems appropriate.

Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Documentation/git-annotate.txt

@@ -7,7 +7,7 @@ git-annotate - Annotate file lines with commit info
 
 SYNOPSIS
 --------
-git annotate [options] file [revision]
+'git annotate' [options] file [revision]
 
 DESCRIPTION
 -----------

Documentation/git-apply.txt

@@ -64,7 +64,7 @@ OPTIONS
 	without using the working tree. This implies '--index'.
 
 --build-fake-ancestor <file>::
-	Newer git-diff output has embedded 'index information'
+	Newer `git-diff` output has embedded 'index information'
 	for each blob to help identify the original version that
 	the patch applies to.  When this flag is given, and if
 	the original versions of the blobs is available locally,
@@ -78,7 +78,7 @@ the information is read from the current index instead.
 	Apply the patch in reverse.
 
 --reject::
-	For atomicity, linkgit:git-apply[1] by default fails the whole patch and
+	For atomicity, `git-apply` by default fails the whole patch and
 	does not touch the working tree when some of the hunks
 	do not apply.  This option makes it apply
 	the parts of the patch that are applicable, and leave the
@@ -102,7 +102,7 @@ the information is read from the current index instead.
 	ever ignored.
 
 --unidiff-zero::
-	By default, linkgit:git-apply[1] expects that the patch being
+	By default, `git-apply` expects that the patch being
 	applied is a unified diff with at least one line of context.
 	This provides good safety measures, but breaks down when
 	applying a diff generated with --unified=0. To bypass these
@@ -113,7 +113,7 @@ discouraged.
 
 --apply::
 	If you use any of the options marked "Turns off
-	'apply'" above, linkgit:git-apply[1] reads and outputs the
+	'apply'" above, `git-apply` reads and outputs the
 	information you asked without actually applying the
 	patch.  Give this flag after those flags to also apply
 	the patch.
@@ -147,7 +147,7 @@ discouraged.
 	considered whitespace errors.
 +
 By default, the command outputs warning messages but applies the patch.
-When linkgit:git-apply[1] is used for statistics and not applying a
+When `git-apply is used for statistics and not applying a
 patch, it defaults to `nowarn`.
 +
 You can use different `<action>` to control this
@@ -191,7 +191,7 @@ apply.whitespace::
 
 Submodules
 ----------
-If the patch contains any changes to submodules then linkgit:git-apply[1]
+If the patch contains any changes to submodules then `git-apply`
 treats these changes as follows.
 
 If --index is specified (explicitly or implicitly), then the submodule

Documentation/git-archimport.txt

@@ -34,12 +34,12 @@ Arch repository.
 Make sure you have a recent version of `tla` available in the path. `tla` must
 know about the repositories you pass to `git-archimport`.
 
-For the initial import `git-archimport` expects to find itself in an empty
+For the initial import, `git-archimport` expects to find itself in an empty
 directory. To follow the development of a project that uses Arch, rerun
 `git-archimport` with the same parameters as the initial import to perform
 incremental imports.
 
-While git-archimport will try to create sensible branch names for the
+While `git-archimport` will try to create sensible branch names for the
 archives that it imports, it is also possible to specify git branch names
 manually.  To do so, write a git branch name after each <archive/branch>
 parameter, separated by a colon.  This way, you can shorten the Arch
@@ -84,7 +84,7 @@ OPTIONS
 
 -o::
 	Use this for compatibility with old-style branch names used by
-	earlier versions of git-archimport.  Old-style branch names
+	earlier versions of `git-archimport`.  Old-style branch names
 	were category--branch, whereas new-style branch names are
 	archive,category--branch--version.  In both cases, names given
 	on the command-line will override the automatically-generated

Documentation/git-archive.txt

@@ -20,13 +20,13 @@ structure for the named tree, and writes it out to the standard
 output.  If <prefix> is specified it is
 prepended to the filenames in the archive.
 
-'git-archive' behaves differently when given a tree ID versus when
+`git-archive` behaves differently when given a tree ID versus when
 given a commit ID or tag ID.  In the first case the current time is
 used as modification time of each file in the archive.  In the latter
 case the commit time as recorded in the referenced commit object is
 used instead.  Additionally the commit ID is stored in a global
 extended pax header if the tar format is used; it can be extracted
-using 'git-get-tar-commit-id'. In ZIP files it is stored as a file
+using `git-get-tar-commit-id`. In ZIP files it is stored as a file
 comment.
 
 OPTIONS
@@ -57,7 +57,7 @@ OPTIONS
 
 --exec=<git-upload-archive>::
 	Used with --remote to specify the path to the
-	git-upload-archive executable on the remote side.
+	`git-upload-archive` on the remote side.
 
 <tree-ish>::
 	The tree or commit to produce an archive for.

Documentation/git-bisect.txt

@@ -26,7 +26,7 @@ on the subcommand:
  git bisect log
  git bisect run <cmd>...
 
-This command uses 'git rev-list --bisect' option to help drive the
+This command uses `git rev-list --bisect` to help drive the
 binary search process to find which change introduced a bug, given an
 old "good" commit object name and a later "bad" commit object name.
 
@@ -215,13 +215,13 @@ tweaks (e.g., s/#define DEBUG 0/#define DEBUG 1/ in a header file, or
 work around other problem this bisection is not interested in")
 applied to the revision being tested.
 
-To cope with such a situation, after the inner git-bisect finds the
+To cope with such a situation, after the inner `git-bisect` finds the
 next revision to test, with the "run" script, you can apply that tweak
 before compiling, run the real test, and after the test decides if the
 revision (possibly with the needed tweaks) passed the test, rewind the
 tree to the pristine state.  Finally the "run" script can exit with
-the status of the real test to let "git bisect run" command loop to
-know the outcome.
+the status of the real test to let the "git bisect run" command loop to
+determine the outcome.
 
 EXAMPLES
 --------

Documentation/git-blame.txt

@@ -21,7 +21,7 @@ last modified the line. Optionally, start annotating from the given revision.
 Also it can limit the range of lines annotated.
 
 This report doesn't tell you anything about lines which have been deleted or
-replaced; you need to use a tool such as linkgit:git-diff[1] or the "pickaxe"
+replaced; you need to use a tool such as `git-diff` or the "pickaxe"
 interface briefly mentioned in the following paragraph.
 
 Apart from supporting file annotation, git also supports searching the
@@ -49,7 +49,7 @@ include::blame-options.txt[]
 	file (see `-M`).  The first number listed is the score.
 	This is the number of alphanumeric characters detected
 	to be moved between or within files.  This must be above
-	a certain threshold for git-blame to consider those lines
+	a certain threshold for `git-blame` to consider those lines
 	of code to have been moved.
 
 -f::

Documentation/git-branch.txt

@@ -37,7 +37,7 @@ working tree to it; use "git checkout <newbranch>" to switch to the
 new branch.
 
 When a local branch is started off a remote branch, git sets up the
-branch so that linkgit:git-pull[1] will appropriately merge from
+branch so that `git-pull` will appropriately merge from
 the remote branch. This behavior may be changed via the global
 `branch.autosetupmerge` configuration flag. That setting can be
 overridden by using the `--track` and `--no-track` options.
@@ -54,7 +54,7 @@ has a reflog then the reflog will also be deleted.
 
 Use -r together with -d to delete remote-tracking branches. Note, that it
 only makes sense to delete remote-tracking branches if they no longer exist
-in remote repository or if linkgit:git-fetch[1] was configured not to fetch
+in remote repository or if `git-fetch` was configured not to fetch
 them again. See also 'prune' subcommand of linkgit:git-remote[1] for way to
 clean up all obsolete remote-tracking branches.
 
@@ -107,14 +107,14 @@ OPTIONS
 	Display the full sha1s in output listing rather than abbreviating them.
 
 --track::
-	When creating a new branch, set up configuration so that git-pull
+	When creating a new branch, set up configuration so that `git-pull`
 	will automatically retrieve data from the start point, which must be
 	a branch. Use this if you always pull from the same upstream branch
 	into the new branch, and if you don't want to use "git pull
 	<repository> <refspec>" explicitly. This behavior is the default
 	when the start point is a remote branch. Set the
 	branch.autosetupmerge configuration variable to `false` if you want
-	git-checkout and git-branch to always behave as if '--no-track' were
+	`git-checkout` and `git-branch` to always behave as if '--no-track' were
 	given. Set it to `always` if you want this behavior when the
 	start-point is either a local or remote branch.
 

Documentation/git-bundle.txt

@@ -21,9 +21,9 @@ Some workflows require that one or more branches of development on one
 machine be replicated on another machine, but the two machines cannot
 be directly connected so the interactive git protocols (git, ssh,
 rsync, http) cannot be used.  This command provides support for
-git-fetch and git-pull to operate by packaging objects and references
+`git-fetch` and `git-pull` to operate by packaging objects and references
 in an archive at the originating machine, then importing those into
-another repository using linkgit:git-fetch[1] and linkgit:git-pull[1]
+another repository using `git-fetch` and `git-pull`
 after moving the archive by some means (i.e., by sneakernet).  As no
 direct connection between repositories exists, the user must specify a
 basis for the bundle that is held by the destination repository: the
@@ -35,14 +35,14 @@ OPTIONS
 
 create <file>::
        Used to create a bundle named 'file'.  This requires the
-       git-rev-list arguments to define the bundle contents.
+       `git-rev-list` arguments to define the bundle contents.
 
 verify <file>::
        Used to check that a bundle file is valid and will apply
        cleanly to the current repository.  This includes checks on the
        bundle format itself as well as checking that the prerequisite
        commits exist and are fully linked in the current repository.
-       git-bundle prints a list of missing commits, if any, and exits
+       `git-bundle` prints a list of missing commits, if any, and exits
        with non-zero status.
 
 list-heads <file>::
@@ -51,16 +51,15 @@ list-heads <file>::
        printed out.
 
 unbundle <file>::
-       Passes the objects in the bundle to linkgit:git-index-pack[1]
+       Passes the objects in the bundle to `git-index-pack`
        for storage in the repository, then prints the names of all
        defined references. If a reflist is given, only references
        matching those in the given list are printed. This command is
-       really plumbing, intended to be called only by
-       linkgit:git-fetch[1].
+       really plumbing, intended to be called only by `git-fetch`.
 
 [git-rev-list-args...]::
-       A list of arguments, acceptable to git-rev-parse and
-       git-rev-list, that specify the specific objects and references
+       A list of arguments, acceptable to `git-rev-parse` and
+       `git-rev-list`, that specify the specific objects and references
        to transport.  For example, "master~10..master" causes the
        current master reference to be packaged along with all objects
        added since its 10th ancestor commit.  There is no explicit
@@ -70,16 +69,16 @@ unbundle <file>::
 
 [refname...]::
        A list of references used to limit the references reported as
-       available. This is principally of use to git-fetch, which
+       available. This is principally of use to `git-fetch`, which
        expects to receive only those references asked for and not
-       necessarily everything in the pack (in this case, git-bundle is
-       acting like linkgit:git-fetch-pack[1]).
+       necessarily everything in the pack (in this case, `git-bundle` is
+       acting like `git-fetch-pack`).
 
 SPECIFYING REFERENCES
 ---------------------
 
-git-bundle will only package references that are shown by
-git-show-ref: this includes heads, tags, and remote heads.  References
+`git-bundle` will only package references that are shown by
+`git-show-ref`: this includes heads, tags, and remote heads.  References
 such as master~1 cannot be packaged, but are perfectly suitable for
 defining the basis.  More than one reference may be packaged, and more
 than one basis can be specified.  The objects packaged are those not

Documentation/git-check-ref-format.txt

@@ -47,7 +47,7 @@ refname expressions (see linkgit:git-rev-parse[1]).  Namely:
 . colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
   value and store it in dstref" in fetch and push operations.
   It may also be used to select a specific object such as with
-  linkgit:git-cat-file[1] "git cat-file blob v1.3.3:refs.c".
+  `git-cat-file`: "git cat-file blob v1.3.3:refs.c".
 
 
 GIT

Documentation/git-checkout-index.txt

@@ -88,7 +88,7 @@ $ find . -name '*.h' -print0 | xargs -0 git checkout-index -f --
 which will force all existing `*.h` files to be replaced with their
 cached copies. If an empty command line implied "all", then this would
 force-refresh everything in the index, which was not the point.  But
-since git-checkout-index accepts --stdin it would be faster to use:
+since `git-checkout-index` accepts --stdin it would be faster to use:
 
 ----------------
 $ find . -name '*.h' -print0 | git checkout-index -f -z --stdin

Documentation/git-checkout.txt

@@ -49,14 +49,14 @@ OPTIONS
 
 -t::
 --track::
-	When creating a new branch, set up configuration so that git-pull
+	When creating a new branch, set up configuration so that `git-pull`
 	will automatically retrieve data from the start point, which must be
 	a branch. Use this if you always pull from the same upstream branch
 	into the new branch, and if you don't want to use "git pull
 	<repository> <refspec>" explicitly. This behavior is the default
 	when the start point is a remote branch. Set the
 	branch.autosetupmerge configuration variable to `false` if you want
-	git-checkout and git-branch to always behave as if '--no-track' were
+	`git-checkout` and `git-branch` to always behave as if '--no-track' were
 	given. Set it to `always` if you want this behavior when the
 	start-point is either a local or remote branch.
 

Documentation/git-cherry-pick.txt

@@ -19,7 +19,7 @@ OPTIONS
 -------
 <commit>::
 	Commit to cherry-pick.
-	For a more complete list of ways to spell commits, see
+	For a more complete list of ways to spell commits, see the
 	"SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1].
 
 -e::

Documentation/git-cherry.txt

@@ -13,8 +13,8 @@ DESCRIPTION
 -----------
 The changeset (or "diff") of each commit between the fork-point and <head>
 is compared against each commit between the fork-point and <upstream>.
-The commits are compared with their 'patch id', obtained from linkgit:git-patch-id[1]
-program.
+The commits are compared with their 'patch id', obtained from
+the `git-patch-id` program.
 
 Every commit that doesn't exist in the <upstream> branch
 has its id (sha1) reported, prefixed by a symbol.  The ones that have
@@ -37,8 +37,8 @@ to and including <limit> are not reported:
               \__*__*__<limit>__-__+__> <head>
 
 
-Because git-cherry compares the changeset rather than the commit id
-(sha1), you can use git-cherry to find out if a commit you made locally
+Because `git-cherry` compares the changeset rather than the commit id
+(sha1), you can use `git-cherry` to find out if a commit you made locally
 has been applied <upstream> under a different commit id.  For example,
 this will happen if you're feeding patches <upstream> via email rather
 than pushing or pulling commits directly.

Documentation/git-citool.txt

@@ -14,9 +14,9 @@ DESCRIPTION
 A Tcl/Tk based graphical interface to review modified files, stage
 them into the index, enter a commit message and record the new
 commit onto the current branch.  This interface is an alternative
-to the less interactive linkgit:git-commit[1] program.
+to the less interactive `git-commit` program.
 
-git-citool is actually a standard alias for 'git gui citool'.
+`git-citool` is actually a standard alias for `git gui citool`.
 See linkgit:git-gui[1] for more details.
 
 Author

Documentation/git-clean.txt

@@ -27,7 +27,7 @@ OPTIONS
 
 -f::
 	If the git configuration specifies clean.requireForce as true,
-	git-clean will refuse to run unless given -f or -n.
+	`git-clean` will refuse to run unless given -f or -n.
 
 -n::
 --dry-run::
@@ -41,7 +41,7 @@ OPTIONS
 -x::
 	Don't use the ignore rules.  This allows removing all untracked
 	files, including build products.  This can be used (possibly in
-	conjunction with linkgit:git-reset[1]) to create a pristine
+	conjunction with `git-reset`) to create a pristine
 	working directory to test a clean build.
 
 -X::

Documentation/git-clone.txt

@@ -68,10 +68,10 @@ it unless you understand what it does. If you clone your
 repository using this option and then delete branches (or use any
 other git command that makes any existing commit unreferenced) in the
 source repository, some objects may become unreferenced (or dangling).
-These objects may be removed by normal git operations (such as git-commit[1])
-which automatically call git-gc[1]. If these objects are removed and
-were referenced by the cloned repository, then the cloned repository
-will become corrupt.
+These objects may be removed by normal git operations (such as `git-commit`)
+which automatically call `git gc --auto`. (See linkgit:git-gc[1].)
+If these objects are removed and were referenced by the cloned repository,
+then the cloned repository will become corrupt.
 
 
 
@@ -88,7 +88,7 @@ will become corrupt.
 --quiet::
 -q::
 	Operate quietly.  This flag is passed to "rsync" and
-	"git-fetch-pack" commands when given.
+	`git-fetch-pack` commands when given.
 
 --no-checkout::
 -n::
@@ -114,7 +114,7 @@ will become corrupt.
 --upload-pack <upload-pack>::
 -u <upload-pack>::
 	When given, and the repository to clone from is handled
-	by 'git-fetch-pack', '--exec=<upload-pack>' is passed to
+	by `git-fetch-pack`, `--exec=<upload-pack>` is passed to
 	the command to specify non-default path for the command
 	run on the other end.