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