NAME
----
-git-diff-index - Compares content and mode of blobs between the index and repository
+git-diff-index - Compare a tree to the working tree or index
SYNOPSIS
DESCRIPTION
-----------
-Compares the content and mode of the blobs found via a tree
-object with the content of the current index and, optionally
-ignoring the stat state of the file on disk. When paths are
-specified, compares only those named paths. Otherwise all
-entries in the index are compared.
+Compares the content and mode of the blobs found in a tree object
+with the corresponding tracked files in the working tree, or with the
+corresponding paths in the index. When <path> arguments are present,
+compares only paths matching those patterns. Otherwise all tracked
+files are compared.
OPTIONS
-------
include::diff-format.txt[]
-Operating Modes
+OPERATING MODES
---------------
You can choose whether you want to trust the index file entirely
-(using the '--cached' flag) or ask the diff logic to show any files
+(using the `--cached` flag) or ask the diff logic to show any files
that don't match the stat state as being "tentatively changed". Both
of these operations are very useful indeed.
-Cached Mode
+CACHED MODE
-----------
-If '--cached' is specified, it allows you to ask:
+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')
asking yourself "what have I already marked for being committed, and
what's the difference to a previous tree".
-Non-cached Mode
+NON-CACHED MODE
---------------
The "non-cached" mode takes a different approach, and is potentially
the more useful of the two in that what it does can't be emulated with
The non-cached version asks the question:
show me the differences between HEAD and the currently checked out
- tree - index contents _and_ files that aren't up-to-date
+ tree - index contents _and_ files that aren't up to date
which is obviously a very useful question too, since that tells you what
you *could* commit. Again, the output matches the 'git diff-tree -r'
torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD
:100644 100664 7476bb... 000000... kernel/sched.c
-i.e., it shows that the tree has changed, and that `kernel/sched.c` has is
-not up-to-date and may contain new stuff. The all-zero sha1 means that to
+i.e., it shows that the tree has changed, and that `kernel/sched.c` is
+not up to date and may contain new stuff. The all-zero sha1 means that to
get the real diff, you need to look at the object in the working directory
directly rather than do an object-to-object diff.