]>
Commit | Line | Data |
---|---|---|
215a7ad1 | 1 | git-diff-index(1) |
2cf565c5 DG |
2 | ================= |
3 | v0.1, May 2005 | |
4 | ||
5 | NAME | |
6 | ---- | |
215a7ad1 | 7 | git-diff-index - Compares content and mode of blobs between the cache and repository |
2cf565c5 DG |
8 | |
9 | ||
10 | SYNOPSIS | |
11 | -------- | |
215a7ad1 | 12 | 'git-diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...] |
2cf565c5 DG |
13 | |
14 | DESCRIPTION | |
15 | ----------- | |
b1c006dd JH |
16 | Compares the content and mode of the blobs found via a tree |
17 | object with the content of the current cache and, optionally | |
18 | ignoring the stat state of the file on disk. When paths are | |
19 | specified, compares only those named paths. Otherwise all | |
20 | entries in the cache are compared. | |
2cf565c5 DG |
21 | |
22 | OPTIONS | |
23 | ------- | |
dda2d79a JH |
24 | include::diff-options.txt[] |
25 | ||
2cf565c5 DG |
26 | <tree-ish>:: |
27 | The id of a tree object to diff against. | |
28 | ||
2cf565c5 DG |
29 | --cached:: |
30 | do not consider the on-disk file at all | |
31 | ||
32 | -m:: | |
33 | By default, files recorded in the index but not checked | |
34 | out are reported as deleted. This flag makes | |
215a7ad1 | 35 | "git-diff-index" say that all non-checked-out files are up |
2cf565c5 DG |
36 | to date. |
37 | ||
38 | Output format | |
39 | ------------- | |
40 | include::diff-format.txt[] | |
41 | ||
42 | Operating Modes | |
43 | --------------- | |
44 | You can choose whether you want to trust the index file entirely | |
45 | (using the '--cached' flag) or ask the diff logic to show any files | |
46 | that don't match the stat state as being "tentatively changed". Both | |
47 | of these operations are very useful indeed. | |
48 | ||
49 | Cached Mode | |
50 | ----------- | |
51 | If '--cached' is specified, it allows you to ask: | |
52 | ||
2c6e4771 | 53 | show me the differences between HEAD and the current cache |
2cf565c5 DG |
54 | contents (the ones I'd write with a "git-write-tree") |
55 | ||
2c6e4771 JS |
56 | For example, let's say that you have worked on your working directory, updated |
57 | some files in the cache and are ready to commit. You want to see eactly | |
58 | *what* you are going to commit is without having to write a new tree | |
59 | object and compare it that way, and to do that, you just do | |
2cf565c5 | 60 | |
215a7ad1 | 61 | git-diff-index --cached $(cat .git/HEAD) |
2cf565c5 DG |
62 | |
63 | Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had | |
215a7ad1 | 64 | done an "git-update-index" to make that effective in the index file. |
2cf565c5 | 65 | "git-diff-files" wouldn't show anything at all, since the index file |
215a7ad1 | 66 | matches my working directory. But doing a "git-diff-index" does: |
2cf565c5 | 67 | |
215a7ad1 | 68 | torvalds@ppc970:~/git> git-diff-index --cached $(cat .git/HEAD) |
2cf565c5 DG |
69 | -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c |
70 | +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c | |
71 | ||
72 | You can trivially see that the above is a rename. | |
73 | ||
215a7ad1 | 74 | In fact, "git-diff-index --cached" *should* always be entirely equivalent to |
2cf565c5 DG |
75 | actually doing a "git-write-tree" and comparing that. Except this one is much |
76 | nicer for the case where you just want to check where you are. | |
77 | ||
215a7ad1 | 78 | So doing a "git-diff-index --cached" is basically very useful when you are |
2cf565c5 DG |
79 | asking yourself "what have I already marked for being committed, and |
80 | what's the difference to a previous tree". | |
81 | ||
82 | Non-cached Mode | |
83 | --------------- | |
84 | The "non-cached" mode takes a different approach, and is potentially | |
85 | the more useful of the two in that what it does can't be emulated with | |
86 | a "git-write-tree" + "git-diff-tree". Thus that's the default mode. | |
87 | The non-cached version asks the question: | |
88 | ||
89 | show me the differences between HEAD and the currently checked out | |
90 | tree - index contents _and_ files that aren't up-to-date | |
91 | ||
92 | which is obviously a very useful question too, since that tells you what | |
93 | you *could* commit. Again, the output matches the "git-diff-tree -r" | |
94 | output to a tee, but with a twist. | |
95 | ||
96 | The twist is that if some file doesn't match the cache, we don't have | |
97 | a backing store thing for it, and we use the magic "all-zero" sha1 to | |
98 | show that. So let's say that you have edited `kernel/sched.c`, but | |
215a7ad1 | 99 | have not actually done a "git-update-index" on it yet - there is no |
2cf565c5 DG |
100 | "object" associated with the new state, and you get: |
101 | ||
215a7ad1 | 102 | torvalds@ppc970:~/v2.6/linux> git-diff-index $(cat .git/HEAD ) |
2cf565c5 DG |
103 | *100644->100664 blob 7476bb......->000000...... kernel/sched.c |
104 | ||
105 | ie it shows that the tree has changed, and that `kernel/sched.c` has is | |
106 | not up-to-date and may contain new stuff. The all-zero sha1 means that to | |
107 | get the real diff, you need to look at the object in the working directory | |
108 | directly rather than do an object-to-object diff. | |
109 | ||
215a7ad1 | 110 | NOTE! As with other commands of this type, "git-diff-index" does not |
2cf565c5 DG |
111 | actually look at the contents of the file at all. So maybe |
112 | `kernel/sched.c` hasn't actually changed, and it's just that you | |
113 | touched it. In either case, it's a note that you need to | |
114 | "git-upate-cache" it to make the cache be in sync. | |
115 | ||
116 | NOTE 2! You can have a mixture of files show up as "has been updated" | |
117 | and "is still dirty in the working directory" together. You can always | |
118 | tell which file is in which state, since the "has been updated" ones | |
119 | show a valid sha1, and the "not in sync with the index" ones will | |
120 | always have the special all-zero sha1. | |
121 | ||
122 | ||
123 | Author | |
124 | ------ | |
125 | Written by Linus Torvalds <torvalds@osdl.org> | |
126 | ||
127 | Documentation | |
128 | -------------- | |
129 | Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. | |
130 | ||
131 | GIT | |
132 | --- | |
133 | Part of the link:git.html[git] suite | |
134 |