Autogenerated man pages for 026351a03507dc3a2e89e068c01234dc55914df2

[git.git] / man1 / git-diff-index.1

.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "GIT-DIFF-INDEX" 1 "" "" ""
.SH NAME
git-diff-index \- Compares content and mode of blobs between the index and repository
.SH "SYNOPSIS"


git\-diff\-index [\-m] [\-\-cached] [<common diff options>] <tree\-ish> [<path>...]

.SH "DESCRIPTION"


Compares the content and mode of the blobs found via a tree object with the content of the current index and, optionally ignoring the stat state of the file on disk\&. When paths are specified, compares only those named paths\&. Otherwise all entries in the index are compared\&.

.SH "OPTIONS"

.TP
\-p
Generate patch (see section on generating patches)

.TP
\-u
Synonym for "\-p"\&.

.TP
\-z
\\0 line termination on output

.TP
\-\-name\-only
Show only names of changed files\&.

.TP
\-\-name\-status
Show only names and status of changed files\&.

.TP
\-\-full\-index
Instead of the first handful characters, show full object name of pre\- and post\-image blob on the "index" line when generating a patch format output\&.

.TP
\-\-abbrev[=<n>]
Instead of showing the full 40\-byte hexadecimal object name in diff\-raw format output and diff\-tree header lines, show only handful hexdigits prefix\&. This is independent of \-\-full\-index option above, which controls the diff\-patch output format\&. Non default number of digits can be specified with \-\-abbrev=<n>\&.

.TP
\-B
Break complete rewrite changes into pairs of delete and create\&.

.TP
\-M
Detect renames\&.

.TP
\-C
Detect copies as well as renames\&.

.TP
\-\-find\-copies\-harder
For performance reasons, by default, \-C option finds copies only if the original file of the copy was modified in the same changeset\&. This flag makes the command inspect unmodified files as candidates for the source of copy\&. This is a very expensive operation for large projects, so use it with caution\&.

.TP
\-l<num>
\-M and \-C options require O(n^2) processing time where n is the number of potential rename/copy targets\&. This option prevents rename/copy detection from running if the number of rename/copy targets exceeds the specified number\&.

.TP
\-S<string>
Look for differences that contain the change in <string>\&.

.TP
\-\-pickaxe\-all
When \-S finds a change, show all the changes in that changeset, not just the files that contain the change in <string>\&.

.TP
\-O<orderfile>
Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line\&.

.TP
\-R
Swap two inputs; that is, show differences from index or on\-disk file to tree contents\&.


For more detailed explanation on these common options, see also diffcore documentation: \fIdiffcore.html\fR\&.

.TP
<tree\-ish>
The id of a tree object to diff against\&.

.TP
\-\-cached
do not consider the on\-disk file at all

.TP
\-m
By default, files recorded in the index but not checked out are reported as deleted\&. This flag makes "git\-diff\-index" say that all non\-checked\-out files are up to date\&.

.SH "OUTPUT FORMAT"


The output format from "git\-diff\-index", "git\-diff\-tree" and "git\-diff\-files" are very similar\&.


These commands all compare two sets of things; what is compared differs:

.TP
git\-diff\-index <tree\-ish>
compares the <tree\-ish> and the files on the filesystem\&.

.TP
git\-diff\-index \-\-cached <tree\-ish>
compares the <tree\-ish> and the index\&.

.TP
git\-diff\-tree [\-r] <tree\-ish\-1> <tree\-ish\-2> [<pattern>...]
compares the trees named by the two arguments\&.

.TP
git\-diff\-files [<pattern>...]
compares the index and the files on the filesystem\&.


An output line is formatted this way:

.IP
in\-place edit  :100644 100644 bcd1234\&.\&.\&. 0123456\&.\&.\&. M file0
copy\-edit      :100644 100644 abcd123\&.\&.\&. 1234567\&.\&.\&. C68 file1 file2
rename\-edit    :100644 100644 abcd123\&.\&.\&. 1234567\&.\&.\&. R86 file1 file3
create         :000000 100644 0000000\&.\&.\&. 1234567\&.\&.\&. A file4
delete         :100644 000000 1234567\&.\&.\&. 0000000\&.\&.\&. D file5
unmerged       :000000 000000 0000000\&.\&.\&. 0000000\&.\&.\&. U file6

That is, from the left to the right:

.TP 3
1.
a colon\&.
.TP
2.
mode for "src"; 000000 if creation or unmerged\&.
.TP
3.
a space\&.
.TP
4.
mode for "dst"; 000000 if deletion or unmerged\&.
.TP
5.
a space\&.
.TP
6.
sha1 for "src"; 0{40} if creation or unmerged\&.
.TP
7.
a space\&.
.TP
8.
sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree"\&.
.TP
9.
a space\&.
.TP
10.
status, followed by optional "score" number\&.
.TP
11.
a tab or a NUL when \-z option is used\&.
.TP
12.
path for "src"
.TP
13.
a tab or a NUL when \-z option is used; only exists for C or R\&.
.TP
14.
path for "dst"; only exists for C or R\&.
.TP
15.
an LF or a NUL when \-z option is used, to terminate the record\&.
.LP


<sha1> is shown as all 0's if a file is new on the filesystem and it is out of sync with the index\&.


Example:

.IP
:100644 100644 5be4a4\&.\&.\&.\&.\&.\&. 000000\&.\&.\&.\&.\&.\&. M file\&.c

When \-z option is not used, TAB, LF, and backslash characters in pathnames are represented as \\t, \\n, and \\\\, respectively\&.

.SH "GENERATING PATCHES WITH -P"


When "git\-diff\-index", "git\-diff\-tree", or "git\-diff\-files" are run with a \-p option, they do not produce the output described above; instead they produce a patch file\&.


The patch generation can be customized at two levels\&.

.TP 3
1.
When the environment variable GIT_EXTERNAL_DIFF is not set, these commands internally invoke "diff" like this:


.nf
diff \-L a/<path> \-L b/<path> \-pu <old> <new>
.fi
For added files, /dev/null is used for <old>\&. For removed files, /dev/null is used for <new>

The "diff" formatting options can be customized via the environment variable GIT_DIFF_OPTS\&. For example, if you prefer context diff:

.nf
GIT_DIFF_OPTS=\-c git\-diff\-index \-p HEAD
.fi
.TP
2.
When the environment variable GIT_EXTERNAL_DIFF is set, the program named by it is called, instead of the diff invocation described above\&.

For a path that is added, removed, or modified, GIT_EXTERNAL_DIFF is called with 7 parameters:


.nf
path old\-file old\-hex old\-mode new\-file new\-hex new\-mode
.fi
where:

<old|new>\-file
are files GIT_EXTERNAL_DIFF can use to read the contents of <old|new>,
<old|new>\-hex
are the 40\-hexdigit SHA1 hashes,
<old|new>\-mode
are the octal representation of the file modes\&.
The file parameters can point at the user's working file (e\&.g\&. new\-file in "git\-diff\-files"), /dev/null (e\&.g\&. old\-file when a new file is added), or a temporary file (e\&.g\&. old\-file in the index)\&. GIT_EXTERNAL_DIFF should not worry about unlinking the temporary file \-\-\- it is removed when GIT_EXTERNAL_DIFF exits\&.
.LP


For a path that is unmerged, GIT_EXTERNAL_DIFF is called with 1 parameter, <path>\&.

.SH "GIT SPECIFIC EXTENSION TO DIFF FORMAT"


What \-p option produces is slightly different from the traditional diff format\&.

.TP 3
1.
It is preceded with a "git diff" header, that looks like this:


.nf
diff \-\-git a/file1 b/file2
.fi
The a/ and b/ filenames are the same unless rename/copy is involved\&. Especially, even for a creation or a deletion, /dev/null is _not_ used in place of a/ or b/ filenames\&.

When rename/copy is involved, file1 and file2 show the name of the source file of the rename/copy and the name of the file that rename/copy produces, respectively\&.
.TP
2.
It is followed by one or more extended header lines:

.nf
old mode <mode>
new mode <mode>
deleted file mode <mode>
new file mode <mode>
copy from <path>
copy to <path>
rename from <path>
rename to <path>
similarity index <number>
dissimilarity index <number>
index <hash>\&.\&.<hash> <mode>
.fi
.TP
3.
TAB, LF, and backslash characters in pathnames are represented as \\t, \\n, and \\\\, respectively\&.
.LP

.SH "OPERATING MODES"


You can choose whether you want to trust the index file entirely (using the \-\-cached flag) or ask the diff logic to show any files that don't match the stat state as being "tentatively changed"\&. Both of these operations are very useful indeed\&.

.SH "CACHED MODE"


If \-\-cached is specified, it allows you to ask:

.nf
show me the differences between HEAD and the current index
contents (the ones I'd write with a "git\-write\-tree")
.fi


For example, let's say that you have worked on your working directory, updated some files in the index and are ready to commit\&. You want to see exactly what you are going to commit is without having to write a new tree object and compare it that way, and to do that, you just do

.nf
git\-diff\-index \-\-cached HEAD
.fi


Example: let's say I had renamed commit\&.c to git\-commit\&.c, and I had done an "git\-update\-index" to make that effective in the index file\&. "git\-diff\-files" wouldn't show anything at all, since the index file matches my working directory\&. But doing a "git\-diff\-index" does:

.nf
torvalds@ppc970:~/git> git\-diff\-index \-\-cached HEAD
\-100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        commit\&.c
+100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        git\-commit\&.c
.fi


You can trivially see that the above is a rename\&.


In fact, "git\-diff\-index \-\-cached" should always be entirely equivalent to actually doing a "git\-write\-tree" and comparing that\&. Except this one is much nicer for the case where you just want to check where you are\&.


So doing a "git\-diff\-index \-\-cached" is basically very useful when you are asking yourself "what have I already marked for being committed, and what's the difference to a previous tree"\&.

.SH "NON-CACHED MODE"


The "non\-cached" mode takes a different approach, and is potentially the more useful of the two in that what it does can't be emulated with a "git\-write\-tree" + "git\-diff\-tree"\&. Thus that's the default mode\&. The non\-cached version asks the question:

.nf
show me the differences between HEAD and the currently checked out
tree \- index contents _and_ files that aren't up\-to\-date
.fi


which is obviously a very useful question too, since that tells you what you could commit\&. Again, the output matches the "git\-diff\-tree \-r" output to a tee, but with a twist\&.


The twist is that if some file doesn't match the index, we don't have a backing store thing for it, and we use the magic "all\-zero" sha1 to show that\&. So let's say that you have edited kernel/sched\&.c, but have not actually done a "git\-update\-index" on it yet \- there is no "object" associated with the new state, and you get:

.nf
torvalds@ppc970:~/v2\&.6/linux> git\-diff\-index HEAD
*100644\->100664 blob    7476bb\&.\&.\&.\&.\&.\&.\->000000\&.\&.\&.\&.\&.\&.      kernel/sched\&.c
.fi


ie it shows that the tree has changed, and that kernel/sched\&.c has is not up\-to\-date and may contain new stuff\&. The all\-zero sha1 means that to get the real diff, you need to look at the object in the working directory directly rather than do an object\-to\-object diff\&.

.RS
.Sh "Note"


As with other commands of this type, "git\-diff\-index" does not actually look at the contents of the file at all\&. So maybe kernel/sched\&.c hasn't actually changed, and it's just that you touched it\&. In either case, it's a note that you need to "git\-update\-index" it to make the index be in sync\&.

.RE

.RS
.Sh "Note"


You can have a mixture of files show up as "has been updated" and "is still dirty in the working directory" together\&. You can always tell which file is in which state, since the "has been updated" ones show a valid sha1, and the "not in sync with the index" ones will always have the special all\-zero sha1\&.

.RE

.SH "AUTHOR"


Written by Linus Torvalds <torvalds@osdl\&.org>

.SH "DOCUMENTATION"


Documentation by David Greaves, Junio C Hamano and the git\-list <git@vger\&.kernel\&.org>\&.

.SH "GIT"


Part of the \fBgit\fR(7) suite