git-apply.txt

   1 git-apply(1)
   2 ============
   3
   4 NAME
   5 ----
   6 git-apply - Apply a patch to files and/or to the index
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git apply' [--stat] [--numstat] [--summary] [--check]
  13           [--index | --intent-to-add] [--3way] [--ours | --theirs | --union]
  14           [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
  15           [--allow-binary-replacement | --binary] [--reject] [-z]
  16           [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
  17           [--ignore-space-change | --ignore-whitespace]
  18           [--whitespace=(nowarn|warn|fix|error|error-all)]
  19           [--exclude=<path>] [--include=<path>] [--directory=<root>]
  20           [--verbose | --quiet] [--unsafe-paths] [--allow-empty] [<patch>...]
  21
  22 DESCRIPTION
  23 -----------
  24 Reads the supplied diff output (i.e. "a patch") and applies it to files.
  25 When running from a subdirectory in a repository, patched paths
  26 outside the directory are ignored.
  27 With the `--index` option, the patch is also applied to the index, and
  28 with the `--cached` option, the patch is only applied to the index.
  29 Without these options, the command applies the patch only to files,
  30 and does not require them to be in a Git repository.
  31
  32 This command applies the patch but does not create a commit.  Use
  33 linkgit:git-am[1] to create commits from patches generated by
  34 linkgit:git-format-patch[1] and/or received by email.
  35
  36 OPTIONS
  37 -------
  38 <patch>...::
  39         The files to read the patch from.  '-' can be used to read
  40         from the standard input.
  41
  42 --stat::
  43         Instead of applying the patch, output diffstat for the
  44         input.  Turns off "apply".
  45
  46 --numstat::
  47         Similar to `--stat`, but shows the number of added and
  48         deleted lines in decimal notation and the pathname without
  49         abbreviation, to make it more machine friendly.  For
  50         binary files, outputs two `-` instead of saying
  51         `0 0`.  Turns off "apply".
  52
  53 --summary::
  54         Instead of applying the patch, output a condensed
  55         summary of information obtained from git diff extended
  56         headers, such as creations, renames, and mode changes.
  57         Turns off "apply".
  58
  59 --check::
  60         Instead of applying the patch, see if the patch is
  61         applicable to the current working tree and/or the index
  62         file and detects errors.  Turns off "apply".
  63
  64 --index::
  65         Apply the patch to both the index and the working tree (or
  66         merely check that it would apply cleanly to both if `--check` is
  67         in effect). Note that `--index` expects index entries and
  68         working tree copies for relevant paths to be identical (their
  69         contents and metadata such as file mode must match), and will
  70         raise an error if they are not, even if the patch would apply
  71         cleanly to both the index and the working tree in isolation.
  72
  73 --cached::
  74         Apply the patch to just the index, without touching the working
  75         tree. If `--check` is in effect, merely check that it would
  76         apply cleanly to the index entry.
  77
  78 --intent-to-add::
  79         When applying the patch only to the working tree, mark new
  80         files to be added to the index later (see `--intent-to-add`
  81         option in linkgit:git-add[1]). This option is ignored unless
  82         running in a Git repository and `--index` is not specified.
  83         Note that `--index` could be implied by other options such
  84         as `--cached` or `--3way`.
  85
  86 -3::
  87 --3way::
  88         Attempt 3-way merge if the patch records the identity of blobs it is supposed
  89         to apply to and we have those blobs available locally, possibly leaving the
  90         conflict markers in the files in the working tree for the user to
  91         resolve.  This option implies the `--index` option unless the
  92         `--cached` option is used, and is incompatible with the `--reject` option.
  93         When used with the `--cached` option, any conflicts are left at higher stages
  94         in the cache.
  95
  96 --ours::
  97 --theirs::
  98 --union::
  99         Instead of leaving conflicts in the file, resolve conflicts favouring
 100         our (or their or both) side of the lines. Requires --3way.
 101
 102 --build-fake-ancestor=<file>::
 103         Newer 'git diff' output has embedded 'index information'
 104         for each blob to help identify the original version that
 105         the patch applies to.  When this flag is given, and if
 106         the original versions of the blobs are available locally,
 107         builds a temporary index containing those blobs.
 108 +
 109 When a pure mode change is encountered (which has no index information),
 110 the information is read from the current index instead.
 111
 112 -R::
 113 --reverse::
 114         Apply the patch in reverse.
 115
 116 --reject::
 117         For atomicity, 'git apply' by default fails the whole patch and
 118         does not touch the working tree when some of the hunks
 119         do not apply.  This option makes it apply
 120         the parts of the patch that are applicable, and leave the
 121         rejected hunks in corresponding *.rej files.
 122
 123 -z::
 124         When `--numstat` has been given, do not munge pathnames,
 125         but use a NUL-terminated machine-readable format.
 126 +
 127 Without this option, pathnames with "unusual" characters are quoted as
 128 explained for the configuration variable `core.quotePath` (see
 129 linkgit:git-config[1]).
 130
 131 -p<n>::
 132         Remove <n> leading path components (separated by slashes) from
 133         traditional diff paths. E.g., with `-p2`, a patch against
 134         `a/dir/file` will be applied directly to `file`. The default is
 135         1.
 136
 137 -C<n>::
 138         Ensure at least <n> lines of surrounding context match before
 139         and after each change.  When fewer lines of surrounding
 140         context exist they all must match.  By default no context is
 141         ever ignored.
 142
 143 --unidiff-zero::
 144         By default, 'git apply' expects that the patch being
 145         applied is a unified diff with at least one line of context.
 146         This provides good safety measures, but breaks down when
 147         applying a diff generated with `--unified=0`. To bypass these
 148         checks use `--unidiff-zero`.
 149 +
 150 Note, for the reasons stated above, the usage of context-free patches is
 151 discouraged.
 152
 153 --apply::
 154         If you use any of the options marked "Turns off
 155         'apply'" above, 'git apply' reads and outputs the
 156         requested information without actually applying the
 157         patch.  Give this flag after those flags to also apply
 158         the patch.
 159
 160 --no-add::
 161         When applying a patch, ignore additions made by the
 162         patch.  This can be used to extract the common part between
 163         two files by first running 'diff' on them and applying
 164         the result with this option, which would apply the
 165         deletion part but not the addition part.
 166
 167 --allow-binary-replacement::
 168 --binary::
 169         Historically we did not allow binary patch application
 170         without an explicit permission from the user, and this
 171         flag was the way to do so.  Currently, we always allow binary
 172         patch application, so this is a no-op.
 173
 174 --exclude=<path-pattern>::
 175         Don't apply changes to files matching the given path pattern. This can
 176         be useful when importing patchsets, where you want to exclude certain
 177         files or directories.
 178
 179 --include=<path-pattern>::
 180         Apply changes to files matching the given path pattern. This can
 181         be useful when importing patchsets, where you want to include certain
 182         files or directories.
 183 +
 184 When `--exclude` and `--include` patterns are used, they are examined in the
 185 order they appear on the command line, and the first match determines if a
 186 patch to each path is used.  A patch to a path that does not match any
 187 include/exclude pattern is used by default if there is no include pattern
 188 on the command line, and ignored if there is any include pattern.
 189
 190 --ignore-space-change::
 191 --ignore-whitespace::
 192         When applying a patch, ignore changes in whitespace in context
 193         lines if necessary.
 194         Context lines will preserve their whitespace, and they will not
 195         undergo whitespace fixing regardless of the value of the
 196         `--whitespace` option. New lines will still be fixed, though.
 197
 198 --whitespace=<action>::
 199         When applying a patch, detect a new or modified line that has
 200         whitespace errors.  What are considered whitespace errors is
 201         controlled by `core.whitespace` configuration.  By default,
 202         trailing whitespaces (including lines that solely consist of
 203         whitespaces) and a space character that is immediately followed
 204         by a tab character inside the initial indent of the line are
 205         considered whitespace errors.
 206 +
 207 By default, the command outputs warning messages but applies the patch.
 208 When `git-apply` is used for statistics and not applying a
 209 patch, it defaults to `nowarn`.
 210 +
 211 You can use different `<action>` values to control this
 212 behavior:
 213 +
 214 * `nowarn` turns off the trailing whitespace warning.
 215 * `warn` outputs warnings for a few such errors, but applies the
 216   patch as-is (default).
 217 * `fix` outputs warnings for a few such errors, and applies the
 218   patch after fixing them (`strip` is a synonym -- the tool
 219   used to consider only trailing whitespace characters as errors, and the
 220   fix involved 'stripping' them, but modern Gits do more).
 221 * `error` outputs warnings for a few such errors, and refuses
 222   to apply the patch.
 223 * `error-all` is similar to `error` but shows all errors.
 224
 225 --inaccurate-eof::
 226         Under certain circumstances, some versions of 'diff' do not correctly
 227         detect a missing new-line at the end of the file. As a result, patches
 228         created by such 'diff' programs do not record incomplete lines
 229         correctly. This option adds support for applying such patches by
 230         working around this bug.
 231
 232 -v::
 233 --verbose::
 234         Report progress to stderr. By default, only a message about the
 235         current patch being applied will be printed. This option will cause
 236         additional information to be reported.
 237
 238 -q::
 239 --quiet::
 240         Suppress stderr output. Messages about patch status and progress
 241         will not be printed.
 242
 243 --recount::
 244         Do not trust the line counts in the hunk headers, but infer them
 245         by inspecting the patch (e.g. after editing the patch without
 246         adjusting the hunk headers appropriately).
 247
 248 --directory=<root>::
 249         Prepend <root> to all filenames.  If a "-p" argument was also passed,
 250         it is applied before prepending the new root.
 251 +
 252 For example, a patch that talks about updating `a/git-gui.sh` to `b/git-gui.sh`
 253 can be applied to the file in the working tree `modules/git-gui/git-gui.sh` by
 254 running `git apply --directory=modules/git-gui`.
 255
 256 --unsafe-paths::
 257         By default, a patch that affects outside the working area
 258         (either a Git controlled working tree, or the current working
 259         directory when "git apply" is used as a replacement of GNU
 260         patch) is rejected as a mistake (or a mischief).
 261 +
 262 When `git apply` is used as a "better GNU patch", the user can pass
 263 the `--unsafe-paths` option to override this safety check.  This option
 264 has no effect when `--index` or `--cached` is in use.
 265
 266 --allow-empty::
 267         Don't return an error for patches containing no diff. This includes
 268         empty patches and patches with commit text only.
 269
 270 CONFIGURATION
 271 -------------
 272
 273 include::includes/cmd-config-section-all.txt[]
 274
 275 include::config/apply.txt[]
 276
 277 SUBMODULES
 278 ----------
 279 If the patch contains any changes to submodules then 'git apply'
 280 treats these changes as follows.
 281
 282 If `--index` is specified (explicitly or implicitly), then the submodule
 283 commits must match the index exactly for the patch to apply.  If any
 284 of the submodules are checked-out, then these check-outs are completely
 285 ignored, i.e., they are not required to be up to date or clean and they
 286 are not updated.
 287
 288 If `--index` is not specified, then the submodule commits in the patch
 289 are ignored and only the absence or presence of the corresponding
 290 subdirectory is checked and (if possible) updated.
 291
 292 SEE ALSO
 293 --------
 294 linkgit:git-am[1].
 295
 296 GIT
 297 ---
 298 Part of the linkgit:git[1] suite