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