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