summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@ppc970.osdl.org>2005-06-03 00:15:32 (GMT)
committerLinus Torvalds <torvalds@ppc970.osdl.org>2005-06-03 00:15:32 (GMT)
commita7b209091ad2a8277727d62ef1193e109b7fe9ff (patch)
tree559857a7a6a989f9e1a4ef3e6b11fb2011133b16
parent65c2e0c349aa5c7f605defb52dc67f1b3658a1b9 (diff)
downloadgit-a7b209091ad2a8277727d62ef1193e109b7fe9ff.zip
git-a7b209091ad2a8277727d62ef1193e109b7fe9ff.tar.gz
git-a7b209091ad2a8277727d62ef1193e109b7fe9ff.tar.bz2
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.
-rw-r--r--Documentation/tutorial.txt41
1 files changed, 28 insertions, 13 deletions
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index 659efbe..6faf743 100644
--- 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