Allow specifying --dirstat cut-off percentage as a floating point number
[git/git.git] / Documentation / diff-options.txt
CommitLineData
c1a95fa6
SO
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
7ifndef::git-format-patch[]
8ifndef::git-diff[]
272bd3cf 9ifndef::git-log[]
c1a95fa6 10:git-diff-core: 1
272bd3cf 11endif::git-log[]
c1a95fa6
SO
12endif::git-diff[]
13endif::git-format-patch[]
14
15ifdef::git-format-patch[]
16-p::
2cfa8330 17--no-stat::
02bc5b03 18 Generate plain patches without any diffstats.
c1a95fa6
SO
19endif::git-format-patch[]
20
21ifndef::git-format-patch[]
dda2d79a 22-p::
a9e67c8c 23-u::
1c9eecff 24--patch::
c1a95fa6
SO
25 Generate patch (see section on generating patches).
26 {git-diff? This is the default.}
27endif::git-format-patch[]
dda2d79a 28
4eb99473 29-U<n>::
4eb99473
RR
30--unified=<n>::
31 Generate diffs with <n> lines of context instead of
02bc5b03
BG
32 the usual three.
33ifndef::git-format-patch[]
dce5ef14 34 Implies `-p`.
02bc5b03 35endif::git-format-patch[]
4eb99473 36
d4cb003f 37ifndef::git-format-patch[]
b5376648
JH
38--raw::
39 Generate the raw format.
c1a95fa6 40 {git-diff-core? This is the default.}
d4cb003f 41endif::git-format-patch[]
b5376648 42
02bc5b03 43ifndef::git-format-patch[]
5c91da25 44--patch-with-raw::
dce5ef14 45 Synonym for `-p --raw`.
02bc5b03 46endif::git-format-patch[]
5c91da25 47
ec74042d 48--patience::
34292bdd
JS
49 Generate a diff using the "patience diff" algorithm.
50
62b4698e 51--stat[=<width>[,<name-width>]]::
5c5b2ea9 52 Generate a diffstat. You can override the default
62b4698e 53 output width for 80-column terminal by `--stat=<width>`.
5c5b2ea9
LT
54 The width of the filename part can be controlled by
55 giving another width to it separated by a comma.
d75f7952 56
74e2abe5 57--numstat::
dce5ef14 58 Similar to `\--stat`, but shows number of added and
74e2abe5 59 deleted lines in decimal notation and pathname without
2f89543e
JH
60 abbreviation, to make it more machine friendly. For
61 binary files, outputs two `-` instead of saying
62 `0 0`.
74e2abe5 63
ebd124c6 64--shortstat::
dce5ef14 65 Output only the last line of the `--stat` format containing total
ebd124c6
NP
66 number of modified files, as well as number of added and deleted
67 lines.
68
333f3fb0
JH
69--dirstat[=<param1,param2,...>]::
70 Output the distribution of relative amount of changes for each
71 sub-directory. The behavior of `--dirstat` can be customized by
72 passing it a comma separated list of parameters.
2d174951
JH
73 The defaults are controlled by the `diff.dirstat` configuration
74 variable (see linkgit:git-config[1]).
333f3fb0 75 The following parameters are available:
204f01a2 76+
333f3fb0
JH
77--
78`changes`;;
79 Compute the dirstat numbers by counting the lines that have been
80 removed from the source, or added to the destination. This ignores
81 the amount of pure code movements within a file. In other words,
82 rearranging lines in a file is not counted as much as other changes.
83 This is the default behavior when no parameter is given.
84`files`;;
85 Compute the dirstat numbers by counting the number of files changed.
86 Each changed file counts equally in the dirstat analysis. This is
87 the computationally cheapest `--dirstat` behavior, since it does
88 not have to look at the file contents at all.
89`cumulative`;;
90 Count changes in a child directory for the parent directory as well.
91 Note that when using `cumulative`, the sum of the percentages
92 reported may exceed 100%. The default (non-cumulative) behavior can
93 be specified with the `noncumulative` parameter.
94<limit>;;
95 An integer parameter specifies a cut-off percent (3% by default).
96 Directories contributing less than this percentage of the changes
97 are not shown in the output.
98--
99+
100Example: The following will count changed files, while ignoring
101directories with less than 10% of the total amount of changed files,
102and accumulating child directory counts in the parent directories:
103`--dirstat=files,10,cumulative`.
fd33777b 104
4bbd261b
SE
105--summary::
106 Output a condensed summary of extended header information
107 such as creations, renames and mode changes.
108
02bc5b03 109ifndef::git-format-patch[]
29353273 110--patch-with-stat::
dce5ef14 111 Synonym for `-p --stat`.
02bc5b03 112endif::git-format-patch[]
29353273 113
d4cb003f 114ifndef::git-format-patch[]
64485b4a 115
dda2d79a 116-z::
5c931c8d
BG
117ifdef::git-log[]
118 Separate the commits with NULs instead of with new newlines.
119+
120Also, when `--raw` or `--numstat` has been given, do not munge
121pathnames and use NULs as output field terminators.
122endif::git-log[]
64485b4a 123ifndef::git-log[]
03aa87ed
CB
124 When `--raw`, `--numstat`, `--name-only` or `--name-status` has been
125 given, do not munge pathnames and use NULs as output field terminators.
5c931c8d 126endif::git-log[]
64485b4a
BG
127+
128Without this option, each pathname output will have TAB, LF, double quotes,
129and backslash characters replaced with `\t`, `\n`, `\"`, and `\\`,
130respectively, and the pathname will be enclosed in double quotes if
131any of those replacements occurred.
dda2d79a
JH
132
133--name-only::
134 Show only names of changed files.
135
946f5f7c 136--name-status::
a6f47b2b
MV
137 Show only names and status of changed files. See the description
138 of the `--diff-filter` option on what the status letters mean.
dda2d79a 139
752c0c24
JS
140--submodule[=<format>]::
141 Chose the output format for submodule differences. <format> can be one of
142 'short' and 'log'. 'short' just shows pairs of commit names, this format
143 is used when this option is not given. 'log' is the default value for this
144 option and lists the commits in that commit range like the 'summary'
145 option of linkgit:git-submodule[1] does.
146
73e9da01 147--color[=<when>]::
b5376648 148 Show colored diff.
73e9da01 149 The value must be always (the default), never, or auto.
b5376648
JH
150
151--no-color::
152 Turn off colored diff, even when the configuration file
153 gives the default to color output.
73e9da01 154 Same as `--color=never`.
b5376648 155
882749a0
TR
156--word-diff[=<mode>]::
157 Show a word diff, using the <mode> to delimit changed words.
158 By default, words are delimited by whitespace; see
159 `--word-diff-regex` below. The <mode> defaults to 'plain', and
160 must be one of:
161+
162--
163color::
164 Highlight changed words using only colors. Implies `--color`.
165plain::
166 Show words as `[-removed-]` and `{+added+}`. Makes no
167 attempts to escape the delimiters if they appear in the input,
168 so the output may be ambiguous.
169porcelain::
170 Use a special line-based format intended for script
171 consumption. Added/removed/unchanged runs are printed in the
172 usual unified diff format, starting with a `+`/`-`/` `
173 character at the beginning of the line and extending to the
174 end of the line. Newlines in the input are represented by a
175 tilde `~` on a line of its own.
176none::
177 Disable word diff again.
178--
179+
180Note that despite the name of the first mode, color is used to
181highlight the changed parts in all modes if enabled.
182
183--word-diff-regex=<regex>::
184 Use <regex> to decide what a word is, instead of considering
185 runs of non-whitespace to be a word. Also implies
186 `--word-diff` unless it was already enabled.
2b6a5417 187+
882749a0 188Every non-overlapping match of the
c4b252c3
TR
189<regex> is considered a word. Anything between these matches is
190considered whitespace and ignored(!) for the purposes of finding
191differences. You may want to append `|[^[:space:]]` to your regular
192expression to make sure that it matches all non-whitespace characters.
193A match that contains a newline is silently truncated(!) at the
194newline.
80c49c3d 195+
98a4d87b
BSSJ
196The regex can also be set via a diff driver or configuration option, see
197linkgit:gitattributes[1] or linkgit:git-config[1]. Giving it explicitly
198overrides any diff driver or configuration setting. Diff drivers
199override configuration settings.
882749a0
TR
200
201--color-words[=<regex>]::
202 Equivalent to `--word-diff=color` plus (if a regex was
203 specified) `--word-diff-regex=<regex>`.
d4cb003f 204endif::git-format-patch[]
f59a59e2 205
b5376648
JH
206--no-renames::
207 Turn off rename detection, even when the configuration
208 file gives the default to do so.
209
02bc5b03 210ifndef::git-format-patch[]
16507fcf
BL
211--check::
212 Warn if changes introduce trailing whitespace
62c64895
WC
213 or an indent that uses a space before a tab. Exits with
214 non-zero status if problems are found. Not compatible with
215 --exit-code.
02bc5b03 216endif::git-format-patch[]
16507fcf 217
80b1e511 218--full-index::
6457e58c
JM
219 Instead of the first handful of characters, show the full
220 pre- and post-image blob object names on the "index"
221 line when generating patch format output.
b5376648
JH
222
223--binary::
dce5ef14
BG
224 In addition to `--full-index`, output a binary diff that
225 can be applied with `git-apply`.
80b1e511 226
913419fc 227--abbrev[=<n>]::
47dd0d59
JH
228 Instead of showing the full 40-byte hexadecimal object
229 name in diff-raw format output and diff-tree header
323b9db8 230 lines, show only a partial prefix. This is
dce5ef14 231 independent of the `--full-index` option above, which controls
913419fc 232 the diff-patch output format. Non default number of
dce5ef14 233 digits can be specified with `--abbrev=<n>`.
47dd0d59 234
cf958afd 235-B[<n>][/<m>]::
37ab5156 236--break-rewrites[=[<n>][/<m>]]::
cf958afd
MM
237 Break complete rewrite changes into pairs of delete and
238 create. This serves two purposes:
239+
240It affects the way a change that amounts to a total rewrite of a file
241not as a series of deletion and insertion mixed together with a very
242few lines that happen to match textually as the context, but as a
243single deletion of everything old followed by a single insertion of
244everything new, and the number `m` controls this aspect of the -B
245option (defaults to 60%). `-B/70%` specifies that less than 30% of the
246original should remain in the result for git to consider it a total
247rewrite (i.e. otherwise the resulting patch will be a series of
248deletion and insertion mixed together with context lines).
249+
250When used with -M, a totally-rewritten file is also considered as the
251source of a rename (usually -M only considers a file that disappeared
252as the source of a rename), and the number `n` controls this aspect of
253the -B option (defaults to 50%). `-B20%` specifies that a change with
254addition and deletion compared to 20% or more of the file's size are
255eligible for being picked up as a possible source of a rename to
256another file.
257
258-M[<n>]::
f611ddc7 259--find-renames[=<n>]::
7ffad250 260ifndef::git-log[]
dda2d79a 261 Detect renames.
7ffad250
JK
262endif::git-log[]
263ifdef::git-log[]
264 If generating diffs, detect and report renames for each commit.
265 For following files across renames while traversing history, see
266 `--follow`.
267endif::git-log[]
cf958afd
MM
268 If `n` is specified, it is a is a threshold on the similarity
269 index (i.e. amount of addition/deletions compared to the
270 file's size). For example, `-M90%` means git should consider a
271 delete/add pair to be a rename if more than 90% of the file
272 hasn't changed.
dda2d79a 273
cf958afd 274-C[<n>]::
f611ddc7 275--find-copies[=<n>]::
ca6c0970 276 Detect copies as well as renames. See also `--find-copies-harder`.
cf958afd 277 If `n` is specified, it has the same meaning as for `-M<n>`.
dda2d79a
JH
278
279--find-copies-harder::
ca6c0970 280 For performance reasons, by default, `-C` option finds copies only
a6080a0a 281 if the original file of the copy was modified in the same
f73ae1fc 282 changeset. This flag makes the command
dda2d79a
JH
283 inspect unmodified files as candidates for the source of
284 copy. This is a very expensive operation for large
ca6c0970
JS
285 projects, so use it with caution. Giving more than one
286 `-C` option has the same effect.
dda2d79a 287
467ddc14
JH
288-D::
289--irreversible-delete::
290 Omit the preimage for deletes, i.e. print only the header but not
291 the diff between the preimage and `/dev/null`. The resulting patch
292 is not meant to be applied with `patch` nor `git apply`; this is
293 solely for people who want to just concentrate on reviewing the
294 text after the change. In addition, the output obviously lack
295 enough information to apply such a patch in reverse, even manually,
296 hence the name of the option.
297+
298When used together with `-B`, omit also the preimage in the deletion part
299of a delete/create pair.
300
8082d8d3 301-l<num>::
dce5ef14 302 The `-M` and `-C` options require O(n^2) processing time where n
f73ae1fc 303 is the number of potential rename/copy targets. This
8082d8d3 304 option prevents rename/copy detection from running if
f73ae1fc 305 the number of rename/copy targets exceeds the specified
8082d8d3
JH
306 number.
307
d4cb003f 308ifndef::git-format-patch[]
f1037448
YD
309--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]::
310 Select only files that are Added (`A`), Copied (`C`),
311 Deleted (`D`), Modified (`M`), Renamed (`R`), have their
312 type (i.e. regular file, symlink, submodule, ...) changed (`T`),
313 are Unmerged (`U`), are
314 Unknown (`X`), or have had their pairing Broken (`B`).
315 Any combination of the filter characters (including none) can be used.
316 When `*` (All-or-none) is added to the combination, all
317 paths are selected if there is any file that matches
318 other criteria in the comparison; if there is no file
319 that matches other criteria, nothing is selected.
320
dda2d79a 321-S<string>::
821d56aa
JK
322 Look for differences that introduce or remove an instance of
323 <string>. Note that this is different than the string simply
324 appearing in diff output; see the 'pickaxe' entry in
325 linkgit:gitdiffcore[7] for more details.
dda2d79a 326
f506b8e8
JH
327-G<regex>::
328 Look for differences whose added or removed line matches
329 the given <regex>.
330
dda2d79a 331--pickaxe-all::
f506b8e8 332 When `-S` or `-G` finds a change, show all the changes in that
f73ae1fc 333 changeset, not just the files that contain the change
dda2d79a
JH
334 in <string>.
335
d01d8c67
PB
336--pickaxe-regex::
337 Make the <string> not a plain string but an extended POSIX
338 regex to match.
d4cb003f 339endif::git-format-patch[]
d01d8c67 340
dda2d79a
JH
341-O<orderfile>::
342 Output the patch in the order specified in the
343 <orderfile>, which has one shell glob pattern per line.
344
d4cb003f 345ifndef::git-format-patch[]
dda2d79a 346-R::
5f3aa197 347 Swap two inputs; that is, show differences from index or
dda2d79a
JH
348 on-disk file to tree contents.
349
c0cb4a06 350--relative[=<path>]::
cd676a51
JH
351 When run from a subdirectory of the project, it can be
352 told to exclude changes outside the directory and show
c0cb4a06
JH
353 pathnames relative to it with this option. When you are
354 not in a subdirectory (e.g. in a bare repository), you
355 can name which subdirectory to make the output relative
356 to by giving a <path> as an argument.
d4cb003f 357endif::git-format-patch[]
cd676a51 358
a9e67c8c 359-a::
d507bb15
SF
360--text::
361 Treat all files as text.
362
a44a0c99 363--ignore-space-at-eol::
0ac7903e 364 Ignore changes in whitespace at EOL.
a44a0c99 365
a9e67c8c 366-b::
8ebe185b 367--ignore-space-change::
0ac7903e
WC
368 Ignore changes in amount of whitespace. This ignores whitespace
369 at line end, and considers all other sequences of one or
370 more whitespace characters to be equivalent.
8ebe185b 371
a9e67c8c 372-w::
8ebe185b 373--ignore-all-space::
0ac7903e
WC
374 Ignore whitespace when comparing lines. This ignores
375 differences even if one line has whitespace where the other
8ebe185b
JN
376 line has none.
377
6d0e674a
RS
378--inter-hunk-context=<lines>::
379 Show the context between diff hunks, up to the specified number
380 of lines, thereby fusing hunks that are close to each other.
381
d4cb003f 382ifndef::git-format-patch[]
41bbf9d5
AR
383--exit-code::
384 Make the program exit with codes similar to diff(1).
385 That is, it exits with 1 if there were differences and
386 0 means no differences.
387
2a18c266 388--quiet::
dce5ef14 389 Disable all output of the program. Implies `--exit-code`.
d4cb003f 390endif::git-format-patch[]
2a18c266 391
72909bef
JS
392--ext-diff::
393 Allow an external diff helper to be executed. If you set an
5162e697
DM
394 external diff driver with linkgit:gitattributes[5], you need
395 to use this option with linkgit:git-log[1] and friends.
72909bef
JS
396
397--no-ext-diff::
398 Disallow external diff drivers.
399
dd44d419
JL
400--ignore-submodules[=<when>]::
401 Ignore changes to submodules in the diff generation. <when> can be
aee9c7d6
JL
402 either "none", "untracked", "dirty" or "all", which is the default
403 Using "none" will consider the submodule modified when it either contains
404 untracked or modified files or its HEAD differs from the commit recorded
405 in the superproject and can be used to override any settings of the
302ad7a9 406 'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When
dd44d419
JL
407 "untracked" is used submodules are not considered dirty when they only
408 contain untracked content (but they are still scanned for modified
409 content). Using "dirty" ignores all changes to the work tree of submodules,
410 only changes to the commits stored in the superproject are shown (this was
411 the behavior until 1.7.0). Using "all" hides all changes to submodules.
50fd9bd8 412
eab9a40b
JS
413--src-prefix=<prefix>::
414 Show the given source prefix instead of "a/".
415
416--dst-prefix=<prefix>::
417 Show the given destination prefix instead of "b/".
418
419--no-prefix::
420 Do not show any source or destination prefix.
421
8db9307c 422For more detailed explanation on these common options, see also
6998e4db 423linkgit:gitdiffcore[7].