If --cached is specified, it allows you to ask:
show me the differences between HEAD and the current index
contents (the ones I'd write using 'git write-tree')
For example, let's say that you have worked on your working
directory, updated some files in the index and are ready to
commit. You want to see exactly what you are going to commit,
without having to write a new tree object and compare it that
way, and to do that, you just do
git diff-index --cached HEAD
Example: let's say I had renamed commit.c to git-commit.c, and I
had done an update-index to make that effective in the index
file. git diff-files wouldn't show anything at all, since the
index file matches my working directory. But doing a git
diff-index does:
torvalds@ppc970:~/git> git diff-index --cached HEAD
-100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c
+100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c
You can see easily that the above is a rename.
In fact, git diff-index --cached should always be entirely
equivalent to actually doing a git write-tree and comparing that.
Except this one is much nicer for the case where you just want to
check where you are.
So doing a git diff-index --cached is basically very useful when
you are asking yourself "what have I already marked for being
committed, and what's the difference to a previous tree".
