Junio C Hamano | 215a7ad | 2005-09-07 17:26:23 -0700 | [diff] [blame] | 1 | git-diff-index(1) |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 2 | ================= |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 3 | |
| 4 | NAME |
| 5 | ---- |
Junio C Hamano | b3d6e6e | 2013-05-19 22:01:20 -0700 | [diff] [blame] | 6 | git-diff-index - Compare a tree to the working tree or index |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
Martin von Zweigbergk | 7791a1d | 2011-07-01 22:38:26 -0400 | [diff] [blame] | 11 | [verse] |
Jean-Noël Avila | 133db54 | 2021-11-06 19:48:52 +0100 | [diff] [blame] | 12 | 'git diff-index' [-m] [--cached] [--merge-base] [<common-diff-options>] <tree-ish> [<path>...] |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 13 | |
| 14 | DESCRIPTION |
| 15 | ----------- |
Elijah Newren | cf6cac2 | 2023-10-08 06:45:03 +0000 | [diff] [blame] | 16 | Compare the content and mode of the blobs found in a tree object |
Junio C Hamano | b3d6e6e | 2013-05-19 22:01:20 -0700 | [diff] [blame] | 17 | with the corresponding tracked files in the working tree, or with the |
| 18 | corresponding paths in the index. When <path> arguments are present, |
Elijah Newren | cf6cac2 | 2023-10-08 06:45:03 +0000 | [diff] [blame] | 19 | compare only paths matching those patterns. Otherwise all tracked |
Junio C Hamano | b3d6e6e | 2013-05-19 22:01:20 -0700 | [diff] [blame] | 20 | files are compared. |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 21 | |
| 22 | OPTIONS |
| 23 | ------- |
Junio C Hamano | dda2d79 | 2005-07-13 12:52:35 -0700 | [diff] [blame] | 24 | include::diff-options.txt[] |
| 25 | |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 26 | <tree-ish>:: |
| 27 | The id of a tree object to diff against. |
| 28 | |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 29 | --cached:: |
Denton Liu | b277b73 | 2020-09-17 00:44:06 -0700 | [diff] [blame] | 30 | Do not consider the on-disk file at all. |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 31 | |
Denton Liu | 0f5a1d4 | 2020-09-20 04:22:25 -0700 | [diff] [blame] | 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 | |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 37 | -m:: |
| 38 | By default, files recorded in the index but not checked |
| 39 | out are reported as deleted. This flag makes |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 40 | 'git diff-index' say that all non-checked-out files are up |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 41 | to date. |
| 42 | |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 43 | include::diff-format.txt[] |
| 44 | |
Nguyễn Thái Ngọc Duy | 76a8788 | 2018-04-30 17:35:33 +0200 | [diff] [blame] | 45 | OPERATING MODES |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 46 | --------------- |
| 47 | You can choose whether you want to trust the index file entirely |
Matthieu Moy | bcf9626 | 2016-06-28 13:40:11 +0200 | [diff] [blame] | 48 | (using the `--cached` flag) or ask the diff logic to show any files |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 49 | that don't match the stat state as being "tentatively changed". Both |
| 50 | of these operations are very useful indeed. |
| 51 | |
Nguyễn Thái Ngọc Duy | 76a8788 | 2018-04-30 17:35:33 +0200 | [diff] [blame] | 52 | CACHED MODE |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 53 | ----------- |
Matthieu Moy | bcf9626 | 2016-06-28 13:40:11 +0200 | [diff] [blame] | 54 | If `--cached` is specified, it allows you to ask: |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 55 | |
Lukas_Sandström | 5f3aa19 | 2005-11-11 02:12:27 +0100 | [diff] [blame] | 56 | show me the differences between HEAD and the current index |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 57 | contents (the ones I'd write using 'git write-tree') |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 58 | |
Johannes Schindelin | 2c6e477 | 2005-08-05 17:05:02 +0200 | [diff] [blame] | 59 | For example, let's say that you have worked on your working directory, updated |
Junio C Hamano | 8943867 | 2005-12-29 01:20:06 -0800 | [diff] [blame] | 60 | some files in the index and are ready to commit. You want to see exactly |
Andy Parkins | 44b27ec | 2006-11-02 12:12:44 +0100 | [diff] [blame] | 61 | *what* you are going to commit, without having to write a new tree |
Johannes Schindelin | 2c6e477 | 2005-08-05 17:05:02 +0200 | [diff] [blame] | 62 | object and compare it that way, and to do that, you just do |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 63 | |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 64 | git diff-index --cached HEAD |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 65 | |
| 66 | Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had |
Jonathan Nieder | 483bc4f | 2008-06-30 13:56:34 -0500 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 69 | matches my working directory. But doing a 'git diff-index' does: |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 70 | |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 71 | torvalds@ppc970:~/git> git diff-index --cached HEAD |
Philippe Blain | 1971510 | 2022-06-13 12:29:43 +0000 | [diff] [blame] | 72 | :100644 000000 4161aecc6700a2eb579e842af0b7f22b98443f74 0000000000000000000000000000000000000000 D commit.c |
| 73 | :000000 100644 0000000000000000000000000000000000000000 4161aecc6700a2eb579e842af0b7f22b98443f74 A git-commit.c |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 74 | |
Andy Parkins | 44b27ec | 2006-11-02 12:12:44 +0100 | [diff] [blame] | 75 | You can see easily that the above is a rename. |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 76 | |
Jonathan Nieder | 483bc4f | 2008-06-30 13:56:34 -0500 | [diff] [blame] | 77 | In fact, `git diff-index --cached` *should* always be entirely equivalent to |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 78 | actually doing a 'git write-tree' and comparing that. Except this one is much |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 79 | nicer for the case where you just want to check where you are. |
| 80 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 81 | So doing a `git diff-index --cached` is basically very useful when you are |
Junio C Hamano | a6080a0 | 2007-06-07 00:04:01 -0700 | [diff] [blame] | 82 | asking yourself "what have I already marked for being committed, and |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 83 | what's the difference to a previous tree". |
| 84 | |
Nguyễn Thái Ngọc Duy | 76a8788 | 2018-04-30 17:35:33 +0200 | [diff] [blame] | 85 | NON-CACHED MODE |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 89 | a 'git write-tree' + 'git diff-tree'. Thus that's the default mode. |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 90 | The non-cached version asks the question: |
| 91 | |
Jonas Fonseca | df8baa4 | 2005-10-03 19:16:30 +0200 | [diff] [blame] | 92 | show me the differences between HEAD and the currently checked out |
Martin Ågren | 7560f54 | 2017-08-23 19:49:35 +0200 | [diff] [blame] | 93 | tree - index contents _and_ files that aren't up to date |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 94 | |
| 95 | which is obviously a very useful question too, since that tells you what |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 96 | you *could* commit. Again, the output matches the 'git diff-tree -r' |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 97 | output to a tee, but with a twist. |
| 98 | |
Lukas_Sandström | 5f3aa19 | 2005-11-11 02:12:27 +0100 | [diff] [blame] | 99 | The twist is that if some file doesn't match the index, we don't have |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 102 | have not actually done a 'git update-index' on it yet - there is no |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 103 | "object" associated with the new state, and you get: |
| 104 | |
Jeff King | 62b42d3 | 2011-05-26 22:33:15 -0400 | [diff] [blame] | 105 | torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD |
Philippe Blain | 1971510 | 2022-06-13 12:29:43 +0000 | [diff] [blame] | 106 | :100644 100644 7476bb5ba 000000000 M kernel/sched.c |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 107 | |
Martin Ågren | 7560f54 | 2017-08-23 19:49:35 +0200 | [diff] [blame] | 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 |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 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 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 113 | NOTE: As with other commands of this type, 'git diff-index' does not |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 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 |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 117 | 'git update-index' it to make the index be in sync. |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 118 | |
Jonas Fonseca | df8baa4 | 2005-10-03 19:16:30 +0200 | [diff] [blame] | 119 | NOTE: You can have a mixture of files show up as "has been updated" |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 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 | |
David Greaves | 2cf565c | 2005-05-10 22:32:30 +0100 | [diff] [blame] | 125 | GIT |
| 126 | --- |
Christian Couder | 9e1f0a8 | 2008-06-06 09:07:32 +0200 | [diff] [blame] | 127 | Part of the linkgit:git[1] suite |