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