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