diff: document diff-filter exclusion
[git/git.git] / Documentation / diff-options.txt
1 // Please don't remove this comment as asciidoc behaves badly when
2 // the first non-empty line is ifdef/ifndef. The symptom is that
3 // without this comment the <git-diff-core> attribute conditionally
4 // defined below ends up being defined unconditionally.
5 // Last checked with asciidoc 7.0.2.
6
7 ifndef::git-format-patch[]
8 ifndef::git-diff[]
9 ifndef::git-log[]
10 :git-diff-core: 1
11 endif::git-log[]
12 endif::git-diff[]
13 endif::git-format-patch[]
14
15 ifdef::git-format-patch[]
16 -p::
17 --no-stat::
18 Generate plain patches without any diffstats.
19 endif::git-format-patch[]
20
21 ifndef::git-format-patch[]
22 -p::
23 -u::
24 --patch::
25 Generate patch (see section on generating patches).
26 ifdef::git-diff[]
27 This is the default.
28 endif::git-diff[]
29 endif::git-format-patch[]
30
31 -s::
32 --no-patch::
33 Suppress diff output. Useful for commands like `git show` that
34 show the patch by default, or to cancel the effect of `--patch`.
35
36 -U<n>::
37 --unified=<n>::
38 Generate diffs with <n> lines of context instead of
39 the usual three.
40 ifndef::git-format-patch[]
41 Implies `-p`.
42 endif::git-format-patch[]
43
44 ifndef::git-format-patch[]
45 --raw::
46 ifndef::git-log[]
47 Generate the diff in raw format.
48 ifdef::git-diff-core[]
49 This is the default.
50 endif::git-diff-core[]
51 endif::git-log[]
52 ifdef::git-log[]
53 For each commit, show a summary of changes using the raw diff
54 format. See the "RAW OUTPUT FORMAT" section of
55 linkgit:git-diff[1]. This is different from showing the log
56 itself in raw format, which you can achieve with
57 `--format=raw`.
58 endif::git-log[]
59 endif::git-format-patch[]
60
61 ifndef::git-format-patch[]
62 --patch-with-raw::
63 Synonym for `-p --raw`.
64 endif::git-format-patch[]
65
66 --minimal::
67 Spend extra time to make sure the smallest possible
68 diff is produced.
69
70 --patience::
71 Generate a diff using the "patience diff" algorithm.
72
73 --histogram::
74 Generate a diff using the "histogram diff" algorithm.
75
76 --diff-algorithm={patience|minimal|histogram|myers}::
77 Choose a diff algorithm. The variants are as follows:
78 +
79 --
80 `default`, `myers`;;
81 The basic greedy diff algorithm. Currently, this is the default.
82 `minimal`;;
83 Spend extra time to make sure the smallest possible diff is
84 produced.
85 `patience`;;
86 Use "patience diff" algorithm when generating patches.
87 `histogram`;;
88 This algorithm extends the patience algorithm to "support
89 low-occurrence common elements".
90 --
91 +
92 For instance, if you configured diff.algorithm variable to a
93 non-default value and want to use the default one, then you
94 have to use `--diff-algorithm=default` option.
95
96 --stat[=<width>[,<name-width>[,<count>]]]::
97 Generate a diffstat. By default, as much space as necessary
98 will be used for the filename part, and the rest for the graph
99 part. Maximum width defaults to terminal width, or 80 columns
100 if not connected to a terminal, and can be overridden by
101 `<width>`. The width of the filename part can be limited by
102 giving another width `<name-width>` after a comma. The width
103 of the graph part can be limited by using
104 `--stat-graph-width=<width>` (affects all commands generating
105 a stat graph) or by setting `diff.statGraphWidth=<width>`
106 (does not affect `git format-patch`).
107 By giving a third parameter `<count>`, you can limit the
108 output to the first `<count>` lines, followed by `...` if
109 there are more.
110 +
111 These parameters can also be set individually with `--stat-width=<width>`,
112 `--stat-name-width=<name-width>` and `--stat-count=<count>`.
113
114 --numstat::
115 Similar to `--stat`, but shows number of added and
116 deleted lines in decimal notation and pathname without
117 abbreviation, to make it more machine friendly. For
118 binary files, outputs two `-` instead of saying
119 `0 0`.
120
121 --shortstat::
122 Output only the last line of the `--stat` format containing total
123 number of modified files, as well as number of added and deleted
124 lines.
125
126 --dirstat[=<param1,param2,...>]::
127 Output the distribution of relative amount of changes for each
128 sub-directory. The behavior of `--dirstat` can be customized by
129 passing it a comma separated list of parameters.
130 The defaults are controlled by the `diff.dirstat` configuration
131 variable (see linkgit:git-config[1]).
132 The following parameters are available:
133 +
134 --
135 `changes`;;
136 Compute the dirstat numbers by counting the lines that have been
137 removed from the source, or added to the destination. This ignores
138 the amount of pure code movements within a file. In other words,
139 rearranging lines in a file is not counted as much as other changes.
140 This is the default behavior when no parameter is given.
141 `lines`;;
142 Compute the dirstat numbers by doing the regular line-based diff
143 analysis, and summing the removed/added line counts. (For binary
144 files, count 64-byte chunks instead, since binary files have no
145 natural concept of lines). This is a more expensive `--dirstat`
146 behavior than the `changes` behavior, but it does count rearranged
147 lines within a file as much as other changes. The resulting output
148 is consistent with what you get from the other `--*stat` options.
149 `files`;;
150 Compute the dirstat numbers by counting the number of files changed.
151 Each changed file counts equally in the dirstat analysis. This is
152 the computationally cheapest `--dirstat` behavior, since it does
153 not have to look at the file contents at all.
154 `cumulative`;;
155 Count changes in a child directory for the parent directory as well.
156 Note that when using `cumulative`, the sum of the percentages
157 reported may exceed 100%. The default (non-cumulative) behavior can
158 be specified with the `noncumulative` parameter.
159 <limit>;;
160 An integer parameter specifies a cut-off percent (3% by default).
161 Directories contributing less than this percentage of the changes
162 are not shown in the output.
163 --
164 +
165 Example: The following will count changed files, while ignoring
166 directories with less than 10% of the total amount of changed files,
167 and accumulating child directory counts in the parent directories:
168 `--dirstat=files,10,cumulative`.
169
170 --summary::
171 Output a condensed summary of extended header information
172 such as creations, renames and mode changes.
173
174 ifndef::git-format-patch[]
175 --patch-with-stat::
176 Synonym for `-p --stat`.
177 endif::git-format-patch[]
178
179 ifndef::git-format-patch[]
180
181 -z::
182 ifdef::git-log[]
183 Separate the commits with NULs instead of with new newlines.
184 +
185 Also, when `--raw` or `--numstat` has been given, do not munge
186 pathnames and use NULs as output field terminators.
187 endif::git-log[]
188 ifndef::git-log[]
189 When `--raw`, `--numstat`, `--name-only` or `--name-status` has been
190 given, do not munge pathnames and use NULs as output field terminators.
191 endif::git-log[]
192 +
193 Without this option, each pathname output will have TAB, LF, double quotes,
194 and backslash characters replaced with `\t`, `\n`, `\"`, and `\\`,
195 respectively, and the pathname will be enclosed in double quotes if
196 any of those replacements occurred.
197
198 --name-only::
199 Show only names of changed files.
200
201 --name-status::
202 Show only names and status of changed files. See the description
203 of the `--diff-filter` option on what the status letters mean.
204
205 --submodule[=<format>]::
206 Specify how differences in submodules are shown. When `--submodule`
207 or `--submodule=log` is given, the 'log' format is used. This format lists
208 the commits in the range like linkgit:git-submodule[1] `summary` does.
209 Omitting the `--submodule` option or specifying `--submodule=short`,
210 uses the 'short' format. This format just shows the names of the commits
211 at the beginning and end of the range. Can be tweaked via the
212 `diff.submodule` configuration variable.
213
214 --color[=<when>]::
215 Show colored diff.
216 `--color` (i.e. without '=<when>') is the same as `--color=always`.
217 '<when>' can be one of `always`, `never`, or `auto`.
218 ifdef::git-diff[]
219 It can be changed by the `color.ui` and `color.diff`
220 configuration settings.
221 endif::git-diff[]
222
223 --no-color::
224 Turn off colored diff.
225 ifdef::git-diff[]
226 This can be used to override configuration settings.
227 endif::git-diff[]
228 It is the same as `--color=never`.
229
230 --word-diff[=<mode>]::
231 Show a word diff, using the <mode> to delimit changed words.
232 By default, words are delimited by whitespace; see
233 `--word-diff-regex` below. The <mode> defaults to 'plain', and
234 must be one of:
235 +
236 --
237 color::
238 Highlight changed words using only colors. Implies `--color`.
239 plain::
240 Show words as `[-removed-]` and `{+added+}`. Makes no
241 attempts to escape the delimiters if they appear in the input,
242 so the output may be ambiguous.
243 porcelain::
244 Use a special line-based format intended for script
245 consumption. Added/removed/unchanged runs are printed in the
246 usual unified diff format, starting with a `+`/`-`/` `
247 character at the beginning of the line and extending to the
248 end of the line. Newlines in the input are represented by a
249 tilde `~` on a line of its own.
250 none::
251 Disable word diff again.
252 --
253 +
254 Note that despite the name of the first mode, color is used to
255 highlight the changed parts in all modes if enabled.
256
257 --word-diff-regex=<regex>::
258 Use <regex> to decide what a word is, instead of considering
259 runs of non-whitespace to be a word. Also implies
260 `--word-diff` unless it was already enabled.
261 +
262 Every non-overlapping match of the
263 <regex> is considered a word. Anything between these matches is
264 considered whitespace and ignored(!) for the purposes of finding
265 differences. You may want to append `|[^[:space:]]` to your regular
266 expression to make sure that it matches all non-whitespace characters.
267 A match that contains a newline is silently truncated(!) at the
268 newline.
269 +
270 The regex can also be set via a diff driver or configuration option, see
271 linkgit:gitattributes[1] or linkgit:git-config[1]. Giving it explicitly
272 overrides any diff driver or configuration setting. Diff drivers
273 override configuration settings.
274
275 --color-words[=<regex>]::
276 Equivalent to `--word-diff=color` plus (if a regex was
277 specified) `--word-diff-regex=<regex>`.
278 endif::git-format-patch[]
279
280 --no-renames::
281 Turn off rename detection, even when the configuration
282 file gives the default to do so.
283
284 ifndef::git-format-patch[]
285 --check::
286 Warn if changes introduce whitespace errors. What are
287 considered whitespace errors is controlled by `core.whitespace`
288 configuration. By default, trailing whitespaces (including
289 lines that solely consist of whitespaces) and a space character
290 that is immediately followed by a tab character inside the
291 initial indent of the line are considered whitespace errors.
292 Exits with non-zero status if problems are found. Not compatible
293 with --exit-code.
294 endif::git-format-patch[]
295
296 --full-index::
297 Instead of the first handful of characters, show the full
298 pre- and post-image blob object names on the "index"
299 line when generating patch format output.
300
301 --binary::
302 In addition to `--full-index`, output a binary diff that
303 can be applied with `git-apply`.
304
305 --abbrev[=<n>]::
306 Instead of showing the full 40-byte hexadecimal object
307 name in diff-raw format output and diff-tree header
308 lines, show only a partial prefix. This is
309 independent of the `--full-index` option above, which controls
310 the diff-patch output format. Non default number of
311 digits can be specified with `--abbrev=<n>`.
312
313 -B[<n>][/<m>]::
314 --break-rewrites[=[<n>][/<m>]]::
315 Break complete rewrite changes into pairs of delete and
316 create. This serves two purposes:
317 +
318 It affects the way a change that amounts to a total rewrite of a file
319 not as a series of deletion and insertion mixed together with a very
320 few lines that happen to match textually as the context, but as a
321 single deletion of everything old followed by a single insertion of
322 everything new, and the number `m` controls this aspect of the -B
323 option (defaults to 60%). `-B/70%` specifies that less than 30% of the
324 original should remain in the result for Git to consider it a total
325 rewrite (i.e. otherwise the resulting patch will be a series of
326 deletion and insertion mixed together with context lines).
327 +
328 When used with -M, a totally-rewritten file is also considered as the
329 source of a rename (usually -M only considers a file that disappeared
330 as the source of a rename), and the number `n` controls this aspect of
331 the -B option (defaults to 50%). `-B20%` specifies that a change with
332 addition and deletion compared to 20% or more of the file's size are
333 eligible for being picked up as a possible source of a rename to
334 another file.
335
336 -M[<n>]::
337 --find-renames[=<n>]::
338 ifndef::git-log[]
339 Detect renames.
340 endif::git-log[]
341 ifdef::git-log[]
342 If generating diffs, detect and report renames for each commit.
343 For following files across renames while traversing history, see
344 `--follow`.
345 endif::git-log[]
346 If `n` is specified, it is a threshold on the similarity
347 index (i.e. amount of addition/deletions compared to the
348 file's size). For example, `-M90%` means Git should consider a
349 delete/add pair to be a rename if more than 90% of the file
350 hasn't changed. Without a `%` sign, the number is to be read as
351 a fraction, with a decimal point before it. I.e., `-M5` becomes
352 0.5, and is thus the same as `-M50%`. Similarly, `-M05` is
353 the same as `-M5%`. To limit detection to exact renames, use
354 `-M100%`. The default similarity index is 50%.
355
356 -C[<n>]::
357 --find-copies[=<n>]::
358 Detect copies as well as renames. See also `--find-copies-harder`.
359 If `n` is specified, it has the same meaning as for `-M<n>`.
360
361 --find-copies-harder::
362 For performance reasons, by default, `-C` option finds copies only
363 if the original file of the copy was modified in the same
364 changeset. This flag makes the command
365 inspect unmodified files as candidates for the source of
366 copy. This is a very expensive operation for large
367 projects, so use it with caution. Giving more than one
368 `-C` option has the same effect.
369
370 -D::
371 --irreversible-delete::
372 Omit the preimage for deletes, i.e. print only the header but not
373 the diff between the preimage and `/dev/null`. The resulting patch
374 is not meant to be applied with `patch` or `git apply`; this is
375 solely for people who want to just concentrate on reviewing the
376 text after the change. In addition, the output obviously lack
377 enough information to apply such a patch in reverse, even manually,
378 hence the name of the option.
379 +
380 When used together with `-B`, omit also the preimage in the deletion part
381 of a delete/create pair.
382
383 -l<num>::
384 The `-M` and `-C` options require O(n^2) processing time where n
385 is the number of potential rename/copy targets. This
386 option prevents rename/copy detection from running if
387 the number of rename/copy targets exceeds the specified
388 number.
389
390 ifndef::git-format-patch[]
391 --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]::
392 Select only files that are Added (`A`), Copied (`C`),
393 Deleted (`D`), Modified (`M`), Renamed (`R`), have their
394 type (i.e. regular file, symlink, submodule, ...) changed (`T`),
395 are Unmerged (`U`), are
396 Unknown (`X`), or have had their pairing Broken (`B`).
397 Any combination of the filter characters (including none) can be used.
398 When `*` (All-or-none) is added to the combination, all
399 paths are selected if there is any file that matches
400 other criteria in the comparison; if there is no file
401 that matches other criteria, nothing is selected.
402 +
403 Also, these upper-case letters can be downcased to exclude. E.g.
404 `--diff-filter=ad` excludes added and deleted paths.
405
406 -S<string>::
407 Look for differences that change the number of occurrences of
408 the specified string (i.e. addition/deletion) in a file.
409 Intended for the scripter's use.
410 +
411 It is useful when you're looking for an exact block of code (like a
412 struct), and want to know the history of that block since it first
413 came into being: use the feature iteratively to feed the interesting
414 block in the preimage back into `-S`, and keep going until you get the
415 very first version of the block.
416
417 -G<regex>::
418 Look for differences whose patch text contains added/removed
419 lines that match <regex>.
420 +
421 To illustrate the difference between `-S<regex> --pickaxe-regex` and
422 `-G<regex>`, consider a commit with the following diff in the same
423 file:
424 +
425 ----
426 + return !regexec(regexp, two->ptr, 1, &regmatch, 0);
427 ...
428 - hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0);
429 ----
430 +
431 While `git log -G"regexec\(regexp"` will show this commit, `git log
432 -S"regexec\(regexp" --pickaxe-regex` will not (because the number of
433 occurrences of that string did not change).
434 +
435 See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more
436 information.
437
438 --pickaxe-all::
439 When `-S` or `-G` finds a change, show all the changes in that
440 changeset, not just the files that contain the change
441 in <string>.
442
443 --pickaxe-regex::
444 Treat the <string> given to `-S` as an extended POSIX regular
445 expression to match.
446 endif::git-format-patch[]
447
448 -O<orderfile>::
449 Output the patch in the order specified in the
450 <orderfile>, which has one shell glob pattern per line.
451 This overrides the `diff.orderFile` configuration variable
452 (see linkgit:git-config[1]). To cancel `diff.orderFile`,
453 use `-O/dev/null`.
454
455 ifndef::git-format-patch[]
456 -R::
457 Swap two inputs; that is, show differences from index or
458 on-disk file to tree contents.
459
460 --relative[=<path>]::
461 When run from a subdirectory of the project, it can be
462 told to exclude changes outside the directory and show
463 pathnames relative to it with this option. When you are
464 not in a subdirectory (e.g. in a bare repository), you
465 can name which subdirectory to make the output relative
466 to by giving a <path> as an argument.
467 endif::git-format-patch[]
468
469 -a::
470 --text::
471 Treat all files as text.
472
473 --ignore-space-at-eol::
474 Ignore changes in whitespace at EOL.
475
476 -b::
477 --ignore-space-change::
478 Ignore changes in amount of whitespace. This ignores whitespace
479 at line end, and considers all other sequences of one or
480 more whitespace characters to be equivalent.
481
482 -w::
483 --ignore-all-space::
484 Ignore whitespace when comparing lines. This ignores
485 differences even if one line has whitespace where the other
486 line has none.
487
488 --ignore-blank-lines::
489 Ignore changes whose lines are all blank.
490
491 --inter-hunk-context=<lines>::
492 Show the context between diff hunks, up to the specified number
493 of lines, thereby fusing hunks that are close to each other.
494
495 -W::
496 --function-context::
497 Show whole surrounding functions of changes.
498
499 ifndef::git-format-patch[]
500 ifndef::git-log[]
501 --exit-code::
502 Make the program exit with codes similar to diff(1).
503 That is, it exits with 1 if there were differences and
504 0 means no differences.
505
506 --quiet::
507 Disable all output of the program. Implies `--exit-code`.
508 endif::git-log[]
509 endif::git-format-patch[]
510
511 --ext-diff::
512 Allow an external diff helper to be executed. If you set an
513 external diff driver with linkgit:gitattributes[5], you need
514 to use this option with linkgit:git-log[1] and friends.
515
516 --no-ext-diff::
517 Disallow external diff drivers.
518
519 --textconv::
520 --no-textconv::
521 Allow (or disallow) external text conversion filters to be run
522 when comparing binary files. See linkgit:gitattributes[5] for
523 details. Because textconv filters are typically a one-way
524 conversion, the resulting diff is suitable for human
525 consumption, but cannot be applied. For this reason, textconv
526 filters are enabled by default only for linkgit:git-diff[1] and
527 linkgit:git-log[1], but not for linkgit:git-format-patch[1] or
528 diff plumbing commands.
529
530 --ignore-submodules[=<when>]::
531 Ignore changes to submodules in the diff generation. <when> can be
532 either "none", "untracked", "dirty" or "all", which is the default.
533 Using "none" will consider the submodule modified when it either contains
534 untracked or modified files or its HEAD differs from the commit recorded
535 in the superproject and can be used to override any settings of the
536 'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When
537 "untracked" is used submodules are not considered dirty when they only
538 contain untracked content (but they are still scanned for modified
539 content). Using "dirty" ignores all changes to the work tree of submodules,
540 only changes to the commits stored in the superproject are shown (this was
541 the behavior until 1.7.0). Using "all" hides all changes to submodules.
542
543 --src-prefix=<prefix>::
544 Show the given source prefix instead of "a/".
545
546 --dst-prefix=<prefix>::
547 Show the given destination prefix instead of "b/".
548
549 --no-prefix::
550 Do not show any source or destination prefix.
551
552 For more detailed explanation on these common options, see also
553 linkgit:gitdiffcore[7].