diff options
| -rw-r--r-- | Documentation/tutorial.txt | 41 |
1 files changed, 28 insertions, 13 deletions
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 659efbe6ba..6faf7435a8 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 |