doc: convert git-apply synopsis and options to new style
Convert git-apply from [verse]/single-quote style to the modern synopsis-block style: - Replace [verse] with [synopsis] in SYNOPSIS block - Backtick-quote all OPTIONS terms and config keys in config/apply.adoc - Convert single-quoted inline commands ('git apply', 'diff', etc.) - Wrap standalone placeholders in underscores (<n>, <root>, <action>) - Backtick-quote `*.rej` and GNU `patch` tool references Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jean-Noël Avila committed
May 25, 2026 at 10:28 UTC
ba1c516edabccd3e195746a8be842a70cdea6502
2 files changed
+74
-68
Documentation/config/apply.adoc
+11
-6
@@ -1,11 +1,16 @@
1
-apply.ignoreWhitespace::
2
- When set to 'change', tells 'git apply' to ignore changes in
1
+`apply.ignoreWhitespace`::
2
+ When set to `change`, tells `git apply` to ignore changes in
3
whitespace, in the same way as the `--ignore-space-change`
4
option.
5
- When set to one of: no, none, never, false, it tells 'git apply' to
5
+ When set to one of: `no`, `none`, `never`, `false`, it tells `git apply` to
6
respect all whitespace differences.
7
+ifndef::git-apply[]
8
See linkgit:git-apply[1].
9
+endif::git-apply[]
10
9
-apply.whitespace::
10
- Tells 'git apply' how to handle whitespace, in the same way
11
- as the `--whitespace` option. See linkgit:git-apply[1].
11
+`apply.whitespace`::
12
+ Tells `git apply` how to handle whitespace, in the same way
13
+ as the `--whitespace` option.
14
+ifndef::git-apply[]
15
+ See linkgit:git-apply[1].
16
+endif::git-apply[]
Documentation/git-apply.adoc
+63
-62
@@ -8,8 +8,8 @@ git-apply - Apply a patch to files and/or to the index
8
9
SYNOPSIS
10
--------
11
-[verse]
12
-'git apply' [--stat] [--numstat] [--summary] [--check]
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]
@@ -35,33 +35,33 @@ 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
38
+`<patch>...`::
39
+ The files to read the patch from. `-` can be used to read
40
from the standard input.
41
42
---stat::
42
+`--stat`::
43
Instead of applying the patch, output diffstat for the
44
input. Turns off "apply".
45
46
---numstat::
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::
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::
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::
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
@@ -70,13 +70,13 @@ OPTIONS
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::
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::
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
@@ -84,8 +84,8 @@ OPTIONS
84
repository. Note that `--index` could be implied by other options
85
such as `--3way`.
86
87
--3::
88
---3way::
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
@@ -94,14 +94,14 @@ OPTIONS
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::
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.
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'
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,
@@ -110,18 +110,18 @@ OPTIONS
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::
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
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.
122
+ rejected hunks in corresponding `*.rej` files.
123
124
--z::
124
+`-z`::
125
When `--numstat` has been given, do not munge pathnames,
126
but use a NUL-terminated machine-readable format.
127
+
@@ -129,20 +129,20 @@ 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
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
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
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
@@ -151,34 +151,34 @@ linkgit:git-config[1]).
151
Note, for the reasons stated above, the usage of context-free patches is
152
discouraged.
153
154
---apply::
154
+`--apply`::
155
If you use any of the options marked "Turns off
156
- 'apply'" above, 'git apply' reads and outputs the
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::
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
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::
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 the given path pattern. This can
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 given path pattern. This can
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
+
@@ -188,15 +188,15 @@ 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::
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>::
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,
@@ -209,7 +209,7 @@ 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
212
+You can use different _<action>_ values to control this
213
behavior:
214
+
215
* `nowarn` turns off the trailing whitespace warning.
@@ -223,48 +223,48 @@ behavior:
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
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
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::
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::
239
+`-q`::
240
+`--quiet`::
241
Suppress stderr output. Messages about patch status and progress
242
will not be printed.
243
244
---recount::
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,
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::
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).
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
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::
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
@@ -273,11 +273,12 @@ CONFIGURATION
273
274
include::includes/cmd-config-section-all.adoc[]
275
276
+:git-apply: 1
277
include::config/apply.adoc[]
278
279
SUBMODULES
280
----------
280
-If the patch contains any changes to submodules then 'git apply'
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