[PATCH] Assorted documentation patches

[jc: Johannes spent time and effort to see how consistent our
use of terminilogy is, and as a byproduct made these corrections
not related to the terminology unification.  I really appreciate
it.]

Signed-off-by: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Signed-off-by: Junio C Hamano <junkio@cox.net>

Documentation/diff-format.txt

@@ -62,7 +62,7 @@ customization also applies to "git-diff-helper".
 1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set,
    these commands internally invoke "diff" like this:
 
-      diff -L a/<path> -L a/<path> -pu <old> <new>
+      diff -L a/<path> -L b/<path> -pu <old> <new>
 +
 For added files, `/dev/null` is used for <old>.  For removed
 files, `/dev/null` is used for <new>
@@ -101,7 +101,7 @@ For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
 parameter, <path>.
 
 
-Git specific extention to diff format
+Git specific extension to diff format
 -------------------------------------
 
 What -p option produces is slightly different from the

Documentation/diff-options.txt

@@ -5,9 +5,9 @@
 	Synonym for "-p".
 
 -r::
-	Look recursivelly in subdirectories; this flag does not
+	Look recursively in subdirectories; this flag does not
 	mean anything to commands other than "git-diff-tree";
-	other commands always looks at all the subdirectories.
+	other diff commands always look at all the subdirectories.
 
 -z::
 	\0 line termination on output

Documentation/git-diff-cache.txt

@@ -50,13 +50,13 @@ Cached Mode
 -----------
 If '--cached' is specified, it allows you to ask:
 
-	show me the differences between HEAD and the current index
+	show me the differences between HEAD and the current cache
 	contents (the ones I'd write with a "git-write-tree")
 
-For example, let's say that you have worked on your index file, and are
-ready to commit. You want to see eactly *what* you are going to commit is
-without having to write a new tree object and compare it that way, and to
-do that, you just do
+For example, let's say that you have worked on your working directory, updated
+some files in the cache and are ready to commit. You want to see eactly
+*what* you are going to commit is without having to write a new tree
+object and compare it that way, and to do that, you just do
 
 	git-diff-cache --cached $(cat .git/HEAD)
 

Documentation/git-diff-tree.txt

@@ -86,7 +86,7 @@ Or if you are searching for what changed in just `kernel/sched.c`, just do
 and it will ignore all differences to other files.
 
 The pattern is always the prefix, and is matched exactly.  There are no
-wildcards.  Even stricter, it has to match complete path comonent.
+wildcards.  Even stricter, it has to match a complete path component.
 I.e. "foo" does not pick up `foobar.h`.  "foo" does match `foo/bar.h`
 so it can be used to name subdirectories.
 

Documentation/git-fsck-cache.txt

@@ -39,17 +39,17 @@ OPTIONS
 
 --standalone::
 	Limit checks to the contents of GIT_OBJECT_DIRECTORY
-	(.git/objects), making sure that it is consistent and
+	($GIT_DIR/objects), making sure that it is consistent and
 	complete without referring to objects found in alternate
 	object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES,
-	nor packed GIT archives found in .git/objects/pack;
+	nor packed GIT archives found in $GIT_DIR/objects/pack;
 	cannot be used with --full.
 
 --full::
 	Check not just objects in GIT_OBJECT_DIRECTORY
-	(.git/objects), but also the ones found in alternate
+	($GIT_DIR/objects), but also the ones found in alternate
 	object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES,
-	and in packed GIT archives found in .git/objects/pack
+	and in packed GIT archives found in $GIT_DIR/objects/pack
 	and corresponding pack subdirectories in alternate
 	object pools; cannot be used with --standalone.
 
@@ -69,11 +69,7 @@ that aren't readable from any of the specified head nodes.
 
 So for example
 
-	git-fsck-cache --unreachable $(cat .git/HEAD)
-
-or, for Cogito users:
-
-	git-fsck-cache --unreachable $(cat .git/refs/heads/*)
+	git-fsck-cache --unreachable $(cat .git/HEAD .git/refs/heads/*)
 
 will do quite a _lot_ of verification on the tree. There are a few
 extra validity tests to be added (make sure that tree objects are
@@ -122,18 +118,18 @@ sha1 mismatch <object>::
 	The database has an object who's sha1 doesn't match the
 	database value.
 	This indicates a serious data integrity problem.
-	(note: this error occured during early git development when
-	the database format changed.)
 
 Environment Variables
 ---------------------
 
 GIT_OBJECT_DIRECTORY::
-	used to specify the object database root (usually .git/objects)
+	used to specify the object database root (usually $GIT_DIR/objects)
 
 GIT_INDEX_FILE::
-	used to specify the cache
+	used to specify the index file of the cache
 
+GIT_ALTERNATE_OBJECT_DIRECTORIES:
+	used to specify additional object database roots (usually unset)
 
 Author
 ------

Documentation/git-hash-object.txt

@@ -21,6 +21,14 @@ This is used by "git-cvsimport-script" to update the cache
 without modifying files in the work tree.  When <type> is not
 specified, it defaults to "blob". 
 
+OPTIONS
+-------
+
+-t <type>::
+	Specify the type (default: "blob").
+
+-w::
+	Actually write the object into the object database.
 
 Author
 ------

Documentation/git-http-pull.txt

@@ -23,8 +23,9 @@ Downloads a remote GIT repository via HTTP.
 	Get all the objects.
 -v::
 	Report what is downloaded.
--w::
-        Writes the commit-id into the filename under $GIT_DIR/refs/ on
+
+-w <filename>::
+        Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on
         the local end after the transfer is complete.
 
 Author

Documentation/git-init-db.txt

@@ -4,7 +4,7 @@ v0.1, May 2005
 
 NAME
 ----
-git-init-db - Creates an empty git object database
+git-init-db - Creates an empty git repository
 
 
 SYNOPSIS
@@ -13,15 +13,16 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-This simply creates an empty git object database - basically a `.git`
-directory and `.git/object/??/` directories.
+This simply creates an empty git repository - basically a `.git` directory
+and `.git/object/??/`, `.git/refs/heads` and `.git/refs/tags` directories,
+and links `.git/HEAD` symbolically to `.git/refs/heads/master`.
 
 If the 'GIT_DIR' environment variable is set then it specifies a path
 to use instead of `./.git` for the base of the repository.
 
 If the object storage directory is specified via the 'GIT_OBJECT_DIRECTORY'
 environment variable then the sha1 directories are created underneath -
-otherwise the default `.git/objects` directory is used.
+otherwise the default `$GIT_DIR/objects` directory is used.
 
 "git-init-db" won't hurt an existing repository.
 

Documentation/git-local-pull.txt

@@ -25,8 +25,9 @@ OPTIONS
 	Get all the objects.
 -v::
 	Report what is downloaded.
--w::
-        Writes the commit-id into the filename under $GIT_DIR/refs/ on
+
+-w <filename>::
+        Writes the commit-id into the filename under $GIT_DIR/refs/<filename> on
         the local end after the transfer is complete.
 
 Author

Documentation/git-ls-files.txt

@@ -87,7 +87,7 @@ detailed information on unmerged paths.
 For an unmerged path, instead of recording a single mode/SHA1 pair,
 the dircache records up to three such pairs; one from tree O in stage
 1, A in stage 2, and B in stage 3.  This information can be used by
-the user (or Cogito) to see what should eventually be recorded at the
+the user (or the porcelain) to see what should eventually be recorded at the
 path. (see read-cache for more information on state)
 
 
@@ -130,7 +130,7 @@ time.  They are built and ordered in the following way:
    are popped off when leaving the directory.
 
 Each pattern in the pattern list specifies "a match pattern" and
-optionally the fate;n either a file that matches the pattern is
+optionally the fate; either a file that matches the pattern is
 considered excluded or included.  A filename is matched against
 the patterns in the three lists; the --exclude-from list is
 checked first, then the --exclude-per-directory list, and then

Documentation/git-ls-tree.txt

@@ -19,7 +19,7 @@ in the current working directory.
 OPTIONS
 -------
 <tree-ish>::
-	Id of a tree.
+	Id of a tree-ish.
 
 -d::
 	show only the named tree entry itself, not its children
@@ -31,7 +31,7 @@ OPTIONS
 	\0 line termination on output
 
 paths::
-	When paths are given, shows them.  Otherwise implicitly
+	When paths are given, show them.  Otherwise implicitly
 	uses the root level of the tree as the sole path argument.
 
 

Documentation/git-merge-cache.txt

@@ -21,7 +21,7 @@ files are passed as arguments 5, 6 and 7.
 OPTIONS
 -------
 --::
-	Interpret all future arguments as filenames.
+	Interpret all following arguments as filenames.
 
 -a::
 	Run merge against all files in the cache that need merging.

Documentation/git-pack-objects.txt

@@ -29,7 +29,7 @@ one-object" format; this is typically done by the smart-pull
 commands when a pack is created on-the-fly for efficient network
 transport by their peers.
 
-Placing both in pack subdirectory of $GIT_OBJECT_DIRECTORY (or
+Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or
 any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES)
 enables GIT to read from such an archive.
 

Documentation/git-peek-remote.txt

@@ -4,7 +4,7 @@ v0.1, July 2005
 
 NAME
 ----
-git-peek-remote - Lists the references on a remote repository.
+git-peek-remote - Lists the references in a remote repository.
 
 
 SYNOPSIS
@@ -20,14 +20,14 @@ OPTIONS
 -------
 --exec=<git-upload-pack>::
 	Use this to specify the path to 'git-upload-pack' on the
-	remote side, if is not found on your $PATH.
-	Installations of sshd ignores the user's environment
+	remote side, if it is not found on your $PATH. Some
+	installations of sshd ignores the user's environment
 	setup scripts for login shells (e.g. .bash_profile) and
 	your privately installed GIT may not be found on the system
 	default $PATH.  Another workaround suggested is to set
 	up your $PATH in ".bashrc", but this flag is for people
 	who do not want to pay the overhead for non-interactive
-	shells by having a lean .bashrc file (they set most of
+	shells, but prefer having a lean .bashrc file (they set most of
 	the things up in .bash_profile).
 
 <host>::

Documentation/git-prune-script.txt

@@ -14,8 +14,9 @@ SYNOPSIS
 DESCRIPTION
 -----------
 This runs "git-fsck-cache --unreachable" program using the heads specified
-on the command line (or `.git/refs/heads/\*` and `.git/refs/tags/\*` if none is
-specified), and prunes all unreachable objects from the object database.
+on the command line (or `$GIT_DIR/refs/heads/\*` and `$GIT_DIR/refs/tags/\*`
+if none is specified), and prunes all unreachable objects from the object
+database.
 
 
 Author

Documentation/git-read-tree.txt

@@ -41,7 +41,7 @@ OPTIONS
 
 Merging
 -------
-If '-m' is specified, "git-read-tree" can performs 3 kinds of
+If '-m' is specified, "git-read-tree" can perform 3 kinds of
 merge, a single tree merge if only 1 tree is given, a
 fast-forward merge with 2 trees, or a 3-way merge if 3 trees are
 provided.
@@ -51,9 +51,9 @@ Single Tree Merge
 ~~~~~~~~~~~~~~~~~
 If only 1 tree is specified, git-read-tree operates as if the user did not
 specify '-m', except that if the original cache has an entry for a
-given pathname; and the contents of the path matches with the tree
+given pathname, and the contents of the path matches with the tree
 being read, the stat info from the cache is used. (In other words, the
-cache's stat()s take precedence over the merged tree's)
+cache's stat()s take precedence over the merged tree's).
 
 That means that if you do a "git-read-tree -m <newtree>" followed by a
 "git-checkout-cache -f -u -a", the "git-checkout-cache" only checks out
@@ -184,7 +184,7 @@ populated.  Here is an outline of how the algorithm works:
   automatically collapse to "merged" state by git-read-tree.
 
 - a file that has _any_ difference what-so-ever in the three trees
-  will stay as separate entries in the index. It's up to "script
+  will stay as separate entries in the index. It's up to "porcelain
   policy" to determine how to remove the non-0 stages, and insert a
   merged version.
 

Documentation/git-tar-tree.txt

@@ -14,7 +14,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 Creates a tar archive containing the tree structure for the named tree.
-When <base> is specified it is added as a leading path as the files in the
+When <base> is specified it is added as a leading path to the files in the
 generated tar archive.
 
 git-tar-tree behaves differently when given a tree ID versus when given

Documentation/git-update-server-info.txt

@@ -16,7 +16,7 @@ DESCRIPTION
 A dumb server that does not do on-the-fly pack generations can
 have some auxiliary information files in $GIT_DIR/info and
 $GIT_OBJECT_DIRECTORY/info directories to help clients discover
-what references and packs the server has and make an optimized
+what references and packs the server has and make optimized
 pull decisions.  This command generates such auxiliary files.
 
 

Documentation/git-write-tree.txt

@@ -4,7 +4,7 @@ v0.1, May 2005
 
 NAME
 ----
-git-write-tree - Creates a tree from the current cache
+git-write-tree - Creates a tree object from the current cache
 
 
 SYNOPSIS