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