Re: I want to release a "git-1.0"

Linus Torvalds wrote:

Anyway, I wrote just a _very_ introductory thing in
Documentation/tutorial.txt, I'll try to update and expand on it later. 
It
basically has a really stupid example of "how to set up a new 
project".

I've been working my way thru the tutorial, trying to up my git clue 
level a bit. One part where things start to go a bit pear-shaped for me 
is in the description of git-diff-files vs. git-diff-cache. The tutorial 
takes pains to emphasize the difference between "working directory 
contents", "index file", and "committed tree", and I'm on board with 
that. What confuses me is the following:

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.
...
[example where git-diff-cache shows difference between working
directory and committed tree]
...
"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

The example and the description of --cached seem to contradict the first 
sentence's description the tool's purpose in life. If it shows you 
differences between a committed tree and the index file, why is it 
looking in my working directory at all? In order to get the behavior the 
first sentence describes you actually have to use --cached.

Am I on right track?

--Adam