path: root/Documentation/git-diff-cache.txt
diff options
Diffstat (limited to 'Documentation/git-diff-cache.txt')
1 files changed, 141 insertions, 0 deletions
diff --git a/Documentation/git-diff-cache.txt b/Documentation/git-diff-cache.txt
new file mode 100644
index 0000000..b54b822
--- /dev/null
+++ b/Documentation/git-diff-cache.txt
@@ -0,0 +1,141 @@
+v0.1, May 2005
+git-diff-cache - Compares content and mode of blobs between the cache and repository
+'git-diff-cache' [-p] [-r] [-z] [-m] [--cached] <tree-ish>
+Compares the content and mode of the blobs found via a tree object
+with the content of the current cache and, optionally ignoring the
+stat state of the file on disk.
+ The id of a tree object to diff against.
+ Generate patch (see section on generating patches)
+ This flag does not mean anything. It is there only to match
+ "git-diff-tree". Unlike "git-diff-tree", "git-diff-cache"
+ always looks at all the subdirectories.
+ \0 line termination on output
+ do not consider the on-disk file at all
+ By default, files recorded in the index but not checked
+ out are reported as deleted. This flag makes
+ "git-diff-cache" say that all non-checked-out files are up
+ to date.
+Output format
+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
+that don't match the stat state as being "tentatively changed". Both
+of these operations are very useful indeed.
+Cached Mode
+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 with a "git-write-tree")
+For example, let's say that you have worked on your index file, and are
+ready to commit. You want to see eactly *what* you are going to commit is
+without having to write a new tree object and compare it that way, and to
+do that, you just do
+ git-diff-cache --cached $(cat .git/HEAD)
+Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had
+done an "git-update-cache" 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-cache" does:
+ torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD)
+ -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c
+ +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c
+You can trivially see that the above is a rename.
+In fact, "git-diff-cache --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-cache --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".
+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
+a "git-write-tree" + "git-diff-tree". Thus that's the default mode.
+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
+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"
+output to a tee, but with a twist.
+The twist is that if some file doesn't match the cache, we don't have
+a backing store thing for it, and we use the magic "all-zero" sha1 to
+show that. So let's say that you have edited `kernel/sched.c`, but
+have not actually done a "git-update-cache" on it yet - there is no
+"object" associated with the new state, and you get:
+ torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD )
+ *100644->100664 blob 7476bb......->000000...... kernel/sched.c
+ie 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
+get the real diff, you need to look at the object in the working directory
+directly rather than do an object-to-object diff.
+NOTE! As with other commands of this type, "git-diff-cache" does not
+actually look at the contents of the file at all. So maybe
+`kernel/sched.c` hasn't actually changed, and it's just that you
+touched it. In either case, it's a note that you need to
+"git-upate-cache" it to make the cache be in sync.
+NOTE 2! You can have a mixture of files show up as "has been updated"
+and "is still dirty in the working directory" together. You can always
+tell which file is in which state, since the "has been updated" ones
+show a valid sha1, and the "not in sync with the index" ones will
+always have the special all-zero sha1.
+Written by Linus Torvalds <>
+Documentation by David Greaves, Junio C Hamano and the git-list <>.
+Part of the link:git.html[git] suite