undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clarify git-diff-cache semantics in the tutorial.

Browse Source 
Adam Kropelin points out that it wasn't all that clear
at all what the thing does. This hopefully helps a bit.
This commit is contained in:
Linus Torvalds 2005-06-02 17:15:32 -07:00
parent 65c2e0c349
commit a7b209091a
1 changed files with 27 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
Documentation/tutorial.txt
View File

@ -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 Unlike "git-diff-files", which showed the difference between the index
file and the working directory, "git-diff-cache" shows the differences file and the working directory, "git-diff-cache" shows the differences
between a committed _tree_ and the index file. In other words, between a committed _tree_ and either the the index file or the working
git-diff-cache wants a tree to be diffed against, and before we did the directory. In other words, git-diff-cache wants a tree to be diffed
commit, we couldn't do that, because we didn't have anything to diff against, and before we did the commit, we couldn't do that, because we
against. didn't have anything to diff against.
But now we can do 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 (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. 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 Now we're comparing the working directory not against the index file,
the tree we just wrote. It just so happens that those two are obviously but against the tree we just wrote. It just so happens that those two
the same. are obviously the same, so we get the same result.
"git-diff-cache" also has a specific flag "--cached", which is used to In other words, "git-diff-cache" normally compares a tree against the
tell it to show the differences purely with the index file, and ignore working directory, but when given the "--cached" flag, it is told to
the current working directory state entirely. Since we just wrote the instead compare against just the index cache contents, and ignore the
index file to HEAD, doing "git-diff-cache --cached -p HEAD" should thus current working directory state entirely. Since we just wrote the index
return an empty set of differences, and that's exactly what it does. 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 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 understand what's going on, keep in mind the difference between "working