blob: 4de1d4c8f11e6065da2c60c0112b72f85af7daa3 [file] [log] [blame]
Junio C Hamano215a7ad2005-09-07 17:26:23 -07001git-diff-index(1)
David Greaves2cf565c2005-05-10 22:32:30 +01002=================
David Greaves2cf565c2005-05-10 22:32:30 +01003
4NAME
5----
Junio C Hamanob3d6e6e2013-05-19 22:01:20 -07006git-diff-index - Compare a tree to the working tree or index
David Greaves2cf565c2005-05-10 22:32:30 +01007
8
9SYNOPSIS
10--------
Martin von Zweigbergk7791a1d2011-07-01 22:38:26 -040011[verse]
Jean-Noël Avila133db542021-11-06 19:48:52 +010012'git diff-index' [-m] [--cached] [--merge-base] [<common-diff-options>] <tree-ish> [<path>...]
David Greaves2cf565c2005-05-10 22:32:30 +010013
14DESCRIPTION
15-----------
Elijah Newrencf6cac22023-10-08 06:45:03 +000016Compare the content and mode of the blobs found in a tree object
Junio C Hamanob3d6e6e2013-05-19 22:01:20 -070017with the corresponding tracked files in the working tree, or with the
18corresponding paths in the index. When <path> arguments are present,
Elijah Newrencf6cac22023-10-08 06:45:03 +000019compare only paths matching those patterns. Otherwise all tracked
Junio C Hamanob3d6e6e2013-05-19 22:01:20 -070020files are compared.
David Greaves2cf565c2005-05-10 22:32:30 +010021
22OPTIONS
23-------
Junio C Hamanodda2d792005-07-13 12:52:35 -070024include::diff-options.txt[]
25
David Greaves2cf565c2005-05-10 22:32:30 +010026<tree-ish>::
27 The id of a tree object to diff against.
28
David Greaves2cf565c2005-05-10 22:32:30 +010029--cached::
Denton Liub277b732020-09-17 00:44:06 -070030 Do not consider the on-disk file at all.
David Greaves2cf565c2005-05-10 22:32:30 +010031
Denton Liu0f5a1d42020-09-20 04:22:25 -070032--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 Greaves2cf565c2005-05-10 22:32:30 +010037-m::
38 By default, files recorded in the index but not checked
39 out are reported as deleted. This flag makes
Thomas Rast0b444cd2010-01-10 00:33:00 +010040 'git diff-index' say that all non-checked-out files are up
David Greaves2cf565c2005-05-10 22:32:30 +010041 to date.
42
David Greaves2cf565c2005-05-10 22:32:30 +010043include::diff-format.txt[]
44
Nguyễn Thái Ngọc Duy76a87882018-04-30 17:35:33 +020045OPERATING MODES
David Greaves2cf565c2005-05-10 22:32:30 +010046---------------
47You can choose whether you want to trust the index file entirely
Matthieu Moybcf96262016-06-28 13:40:11 +020048(using the `--cached` flag) or ask the diff logic to show any files
David Greaves2cf565c2005-05-10 22:32:30 +010049that don't match the stat state as being "tentatively changed". Both
50of these operations are very useful indeed.
51
Nguyễn Thái Ngọc Duy76a87882018-04-30 17:35:33 +020052CACHED MODE
David Greaves2cf565c2005-05-10 22:32:30 +010053-----------
Matthieu Moybcf96262016-06-28 13:40:11 +020054If `--cached` is specified, it allows you to ask:
David Greaves2cf565c2005-05-10 22:32:30 +010055
Lukas_Sandström5f3aa192005-11-11 02:12:27 +010056 show me the differences between HEAD and the current index
Thomas Rast0b444cd2010-01-10 00:33:00 +010057 contents (the ones I'd write using 'git write-tree')
David Greaves2cf565c2005-05-10 22:32:30 +010058
Johannes Schindelin2c6e4772005-08-05 17:05:02 +020059For example, let's say that you have worked on your working directory, updated
Junio C Hamano89438672005-12-29 01:20:06 -080060some files in the index and are ready to commit. You want to see exactly
Andy Parkins44b27ec2006-11-02 12:12:44 +010061*what* you are going to commit, without having to write a new tree
Johannes Schindelin2c6e4772005-08-05 17:05:02 +020062object and compare it that way, and to do that, you just do
David Greaves2cf565c2005-05-10 22:32:30 +010063
Jonathan Niederb1889c32008-06-30 01:09:04 -050064 git diff-index --cached HEAD
David Greaves2cf565c2005-05-10 22:32:30 +010065
66Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had
Jonathan Nieder483bc4f2008-06-30 13:56:34 -050067done 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 Rast0b444cd2010-01-10 00:33:00 +010069matches my working directory. But doing a 'git diff-index' does:
David Greaves2cf565c2005-05-10 22:32:30 +010070
Jonathan Niederb1889c32008-06-30 01:09:04 -050071 torvalds@ppc970:~/git> git diff-index --cached HEAD
Philippe Blain19715102022-06-13 12:29:43 +000072 :100644 000000 4161aecc6700a2eb579e842af0b7f22b98443f74 0000000000000000000000000000000000000000 D commit.c
73 :000000 100644 0000000000000000000000000000000000000000 4161aecc6700a2eb579e842af0b7f22b98443f74 A git-commit.c
David Greaves2cf565c2005-05-10 22:32:30 +010074
Andy Parkins44b27ec2006-11-02 12:12:44 +010075You can see easily that the above is a rename.
David Greaves2cf565c2005-05-10 22:32:30 +010076
Jonathan Nieder483bc4f2008-06-30 13:56:34 -050077In fact, `git diff-index --cached` *should* always be entirely equivalent to
Thomas Rast0b444cd2010-01-10 00:33:00 +010078actually doing a 'git write-tree' and comparing that. Except this one is much
David Greaves2cf565c2005-05-10 22:32:30 +010079nicer for the case where you just want to check where you are.
80
Thomas Rast0b444cd2010-01-10 00:33:00 +010081So doing a `git diff-index --cached` is basically very useful when you are
Junio C Hamanoa6080a02007-06-07 00:04:01 -070082asking yourself "what have I already marked for being committed, and
David Greaves2cf565c2005-05-10 22:32:30 +010083what's the difference to a previous tree".
84
Nguyễn Thái Ngọc Duy76a87882018-04-30 17:35:33 +020085NON-CACHED MODE
David Greaves2cf565c2005-05-10 22:32:30 +010086---------------
87The "non-cached" mode takes a different approach, and is potentially
88the more useful of the two in that what it does can't be emulated with
Thomas Rast0b444cd2010-01-10 00:33:00 +010089a 'git write-tree' + 'git diff-tree'. Thus that's the default mode.
David Greaves2cf565c2005-05-10 22:32:30 +010090The non-cached version asks the question:
91
Jonas Fonsecadf8baa42005-10-03 19:16:30 +020092 show me the differences between HEAD and the currently checked out
Martin Ågren7560f542017-08-23 19:49:35 +020093 tree - index contents _and_ files that aren't up to date
David Greaves2cf565c2005-05-10 22:32:30 +010094
95which is obviously a very useful question too, since that tells you what
Thomas Rast0b444cd2010-01-10 00:33:00 +010096you *could* commit. Again, the output matches the 'git diff-tree -r'
David Greaves2cf565c2005-05-10 22:32:30 +010097output to a tee, but with a twist.
98
Lukas_Sandström5f3aa192005-11-11 02:12:27 +010099The twist is that if some file doesn't match the index, we don't have
David Greaves2cf565c2005-05-10 22:32:30 +0100100a backing store thing for it, and we use the magic "all-zero" sha1 to
101show that. So let's say that you have edited `kernel/sched.c`, but
Thomas Rast0b444cd2010-01-10 00:33:00 +0100102have not actually done a 'git update-index' on it yet - there is no
David Greaves2cf565c2005-05-10 22:32:30 +0100103"object" associated with the new state, and you get:
104
Jeff King62b42d32011-05-26 22:33:15 -0400105 torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD
Philippe Blain19715102022-06-13 12:29:43 +0000106 :100644 100644 7476bb5ba 000000000 M kernel/sched.c
David Greaves2cf565c2005-05-10 22:32:30 +0100107
Martin Ågren7560f542017-08-23 19:49:35 +0200108i.e., it shows that the tree has changed, and that `kernel/sched.c` is
109not up to date and may contain new stuff. The all-zero sha1 means that to
David Greaves2cf565c2005-05-10 22:32:30 +0100110get the real diff, you need to look at the object in the working directory
111directly rather than do an object-to-object diff.
112
Thomas Rast0b444cd2010-01-10 00:33:00 +0100113NOTE: As with other commands of this type, 'git diff-index' does not
David Greaves2cf565c2005-05-10 22:32:30 +0100114actually 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
116touched it. In either case, it's a note that you need to
Thomas Rast0b444cd2010-01-10 00:33:00 +0100117'git update-index' it to make the index be in sync.
David Greaves2cf565c2005-05-10 22:32:30 +0100118
Jonas Fonsecadf8baa42005-10-03 19:16:30 +0200119NOTE: You can have a mixture of files show up as "has been updated"
David Greaves2cf565c2005-05-10 22:32:30 +0100120and "is still dirty in the working directory" together. You can always
121tell which file is in which state, since the "has been updated" ones
122show a valid sha1, and the "not in sync with the index" ones will
123always have the special all-zero sha1.
124
David Greaves2cf565c2005-05-10 22:32:30 +0100125GIT
126---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200127Part of the linkgit:git[1] suite