user-manual: use pithier example commit

diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 1f21d95684a476a7e771ef166536415b5fe81a3c..acb57447a864a54b3b531b7ef7403563fd20f886 100644 (file)
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -8,7 +8,7 @@ git-read-tree - Reads tree information into the index
 
 SYNOPSIS
 --------
-'git-read-tree' (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]])
+'git-read-tree' (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] [--index-output=<file>] <tree-ish1> [<tree-ish2> [<tree-ish3>]])
 
 
 DESCRIPTION
@@ -71,6 +71,32 @@ OPTIONS
        directory.  Note that the `<prefix>/` value must end
        with a slash.
 
+--exclude-per-directory=<gitignore>::
+       When running the command with `-u` and `-m` options, the
+       merge result may need to overwrite paths that are not
+       tracked in the current branch.  The command usually
+       refuses to proceed with the merge to avoid losing such a
+       path.  However this safety valve sometimes gets in the
+       way.  For example, it often happens that the other
+       branch added a file that used to be a generated file in
+       your branch, and the safety valve triggers when you try
+       to switch to that branch after you ran `make` but before
+       running `make clean` to remove the generated file.  This
+       option tells the command to read per-directory exclude
+       file (usually '.gitignore') and allows such an untracked
+       but explicitly ignored file to be overwritten.
+
+--index-output=<file>::
+       Instead of writing the results out to `$GIT_INDEX_FILE`,
+       write the resulting index in the named file.  While the
+       command is operating, the original index file is locked
+       with the same mechanism as usual.  The file must allow
+       to be rename(2)ed into from a temporary file that is
+       created next to the usual index file; typically this
+       means it needs to be on the same filesystem as the index
+       file itself, and you need write permission to the
+       directories the index file and index output file are
+       located in.
 
 <tree-ish#>::
        The id of the tree object(s) to be read/merged.
@@ -214,7 +240,7 @@ The `git-write-tree` command refuses to write a nonsensical tree, and it
 will complain about unmerged entries if it sees a single entry that is not
 stage 0.
 
-Ok, this all sounds like a collection of totally nonsensical rules,
+OK, this all sounds like a collection of totally nonsensical rules,
 but it's actually exactly what you want in order to do a fast
 merge. The different stages represent the "result tree" (stage 0, aka
 "merged"), the original tree (stage 1, aka "orig"), and the two trees
@@ -235,7 +261,7 @@ populated.  Here is an outline of how the algorithm works:
 
 - the index file saves and restores with all this information, so you
   can merge things incrementally, but as long as it has entries in
-  stages 1/2/3 (ie "unmerged entries") you can't write the result. So
+  stages 1/2/3 (i.e., "unmerged entries") you can't write the result. So
   now the merge algorithm ends up being really simple:
 
   * you walk the index in order, and ignore all entries of stage 0,
@@ -266,7 +292,7 @@ file that does not match stage 2.
 This is done to prevent you from losing your work-in-progress
 changes, and mixing your random changes in an unrelated merge
 commit.  To illustrate, suppose you start from what has been
-commited last to your repository:
+committed last to your repository:
 
 ----------------
 $ JC=`git-rev-parse --verify "HEAD^0"`
@@ -315,7 +341,8 @@ have finished your work-in-progress), attempt the merge again.
 
 See Also
 --------
-gitlink:git-write-tree[1]; gitlink:git-ls-files[1]
+gitlink:git-write-tree[1]; gitlink:git-ls-files[1];
+gitlink:gitignore[5]
 
 
 Author