Clarify git-diff-cache semantics in the tutorial.

Adam Kropelin points out that it wasn't all that clear
at all what the thing does. This hopefully helps a bit.

diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index 659efbe6bad830338638b81204ecc3058abd9bbb..6faf7435a821d8d54f2e0653f1bb8726af4132cd 100644 (file)
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -298,10 +298,10 @@ have committed something, we can also learn to use a new command:
 
 Unlike "git-diff-files", which showed the difference between the index
 file and the working directory, "git-diff-cache" shows the differences
-between a committed _tree_ and the index file.  In other words,
-git-diff-cache wants a tree to be diffed against, and before we did the
-commit, we couldn't do that, because we didn't have anything to diff
-against. 
+between a committed _tree_ and either the the index file or the working
+directory.  In other words, git-diff-cache wants a tree to be diffed
+against, and before we did the commit, we couldn't do that, because we
+didn't have anything to diff against. 
 
 But now we can do 
 
@@ -309,15 +309,30 @@ But now we can do
 
 (where "-p" has the same meaning as it did in git-diff-files), and it
 will show us the same difference, but for a totally different reason. 
-Now we're not comparing against the index file, we're comparing against
-the tree we just wrote.  It just so happens that those two are obviously
-the same. 
-
-"git-diff-cache" also has a specific flag "--cached", which is used to
-tell it to show the differences purely with the index file, and ignore
-the current working directory state entirely.  Since we just wrote the
-index file to HEAD, doing "git-diff-cache --cached -p HEAD" should thus
-return an empty set of differences, and that's exactly what it does. 
+Now we're comparing the working directory not against the index file,
+but against the tree we just wrote.  It just so happens that those two
+are obviously the same, so we get the same result.
+
+In other words, "git-diff-cache" normally compares a tree against the
+working directory, but when given the "--cached" flag, it is told to
+instead compare against just the index cache contents, and ignore the
+current working directory state entirely.  Since we just wrote the index
+file to HEAD, doing "git-diff-cache --cached -p HEAD" should thus return
+an empty set of differences, and that's exactly what it does. 
+
+[ Digression: "git-diff-cache" really always uses the index for its
+  comparisons, and saying that it compares a tree against the working
+  directory is thus not strictly accurate. In particular, the list of
+  files to compare (the "meta-data") _always_ comes from the index file,
+  regardless of whether the --cached flag is used or not. The --cached
+  flag really only determines whether the file _contents_ to be compared
+  come from the working directory or not.
+
+  This is not hard to understand, as soon as you realize that git simply
+  never knows (or cares) about files that it is not told about
+  explicitly. Git will never go _looking_ for files to compare, it
+  expects you to tell it what the files are, and that's what the index
+  is there for.  ]
 
 However, our next step is to commit the _change_ we did, and again, to
 understand what's going on, keep in mind the difference between "working