doc: convert git-grep synopsis and options to new style
Convert git-grep.adoc from [verse]/single-quote style to the modern synopsis-block style: - Replace [verse] with [synopsis] in SYNOPSIS block - Change 'git grep' to git grep (no single quotes) - Backtick-quote all OPTIONS terms - Convert inline man page refs: grep(1) -> `grep`(1) - Convert inline command refs: 'git diff' -> `git diff` - Convert prose placeholders: <file> -> _<file>_ 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
25d5d60958f1486cb8439863062f66ffef605f18
2 files changed
+116
-116
Documentation/config/grep.adoc
+18
-18
@@ -1,28 +1,28 @@
1
-grep.lineNumber::
2
- If set to true, enable `-n` option by default.
1
+`grep.lineNumber`::
2
+ If set to `true`, enable `-n` option by default.
3
4
-grep.column::
5
- If set to true, enable the `--column` option by default.
4
+`grep.column`::
5
+ If set to `true`, enable the `--column` option by default.
6
7
-grep.patternType::
8
- Set the default matching behavior. Using a value of 'basic', 'extended',
9
- 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
7
+`grep.patternType`::
8
+ Set the default matching behavior. Using a value of `basic`, `extended`,
9
+ `fixed`, or `perl` will enable the `--basic-regexp`, `--extended-regexp`,
10
`--fixed-strings`, or `--perl-regexp` option accordingly, while the
11
- value 'default' will use the `grep.extendedRegexp` option to choose
12
- between 'basic' and 'extended'.
11
+ value `default` will use the `grep.extendedRegexp` option to choose
12
+ between `basic` and `extended`.
13
14
-grep.extendedRegexp::
15
- If set to true, enable `--extended-regexp` option by default. This
14
+`grep.extendedRegexp`::
15
+ If set to `true`, enable `--extended-regexp` option by default. This
16
option is ignored when the `grep.patternType` option is set to a value
17
- other than 'default'.
17
+ other than `default`.
18
19
-grep.threads::
19
+`grep.threads`::
20
Number of grep worker threads to use. If unset (or set to 0), Git will
21
use as many threads as the number of logical cores available.
22
23
-grep.fullName::
24
- If set to true, enable `--full-name` option by default.
23
+`grep.fullName`::
24
+ If set to `true`, enable `--full-name` option by default.
25
26
-grep.fallbackToNoIndex::
27
- If set to true, fall back to `git grep --no-index` if `git grep`
28
- is executed outside of a git repository. Defaults to false.
26
+`grep.fallbackToNoIndex`::
27
+ If set to `true`, fall back to `git grep --no-index` if `git grep`
28
+ is executed outside of a git repository. Defaults to `false`.
Documentation/git-grep.adoc
+98
-98
@@ -8,8 +8,8 @@ git-grep - Print lines matching a pattern
8
9
SYNOPSIS
10
--------
11
-[verse]
12
-'git grep' [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp]
11
+[synopsis]
12
+git grep [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp]
13
[-v | --invert-match] [-h|-H] [--full-name]
14
[-E | --extended-regexp] [-G | --basic-regexp]
15
[-P | --perl-regexp]
@@ -41,139 +41,139 @@ characters. An empty string as search expression matches all lines.
41
42
OPTIONS
43
-------
44
---cached::
44
+`--cached`::
45
Instead of searching tracked files in the working tree, search
46
blobs registered in the index file.
47
48
---untracked::
48
+`--untracked`::
49
In addition to searching in the tracked files in the working
50
tree, search also in untracked files.
51
52
---no-index::
52
+`--no-index`::
53
Search files in the current directory that is not managed by Git,
54
or by ignoring that the current directory is managed by Git. This
55
- is rather similar to running the regular `grep(1)` utility with its
55
+ is rather similar to running the regular `grep`(1) utility with its
56
`-r` option specified, but with some additional benefits, such as
57
- using pathspec patterns to limit paths; see the 'pathspec' entry
57
+ using pathspec patterns to limit paths; see the `pathspec` entry
58
in linkgit:gitglossary[7] for more information.
59
+
60
This option cannot be used together with `--cached` or `--untracked`.
61
See also `grep.fallbackToNoIndex` in 'CONFIGURATION' below.
62
63
---no-exclude-standard::
63
+`--no-exclude-standard`::
64
Also search in ignored files by not honoring the `.gitignore`
65
mechanism. Only useful with `--untracked`.
66
67
---exclude-standard::
67
+`--exclude-standard`::
68
Do not pay attention to ignored files specified via the `.gitignore`
69
mechanism. Only useful when searching files in the current directory
70
with `--no-index`.
71
72
---recurse-submodules::
72
+`--recurse-submodules`::
73
Recursively search in each submodule that is active and
74
checked out in the repository. When used in combination with the
75
_<tree>_ option the prefix of all submodule output will be the name of
76
the parent project's _<tree>_ object. This option cannot be used together
77
with `--untracked`, and it has no effect if `--no-index` is specified.
78
79
--a::
80
---text::
79
+`-a`::
80
+`--text`::
81
Process binary files as if they were text.
82
83
---textconv::
83
+`--textconv`::
84
Honor textconv filter settings.
85
86
---no-textconv::
86
+`--no-textconv`::
87
Do not honor textconv filter settings.
88
This is the default.
89
90
--i::
91
---ignore-case::
90
+`-i`::
91
+`--ignore-case`::
92
Ignore case differences between the patterns and the
93
files.
94
95
--I::
95
+`-I`::
96
Don't match the pattern in binary files.
97
98
---max-depth <depth>::
99
- For each <pathspec> given on command line, descend at most <depth>
98
+`--max-depth <depth>`::
99
+ For each _<pathspec>_ given on command line, descend at most _<depth>_
100
levels of directories. A value of -1 means no limit.
101
- This option is ignored if <pathspec> contains active wildcards.
101
+ This option is ignored if _<pathspec>_ contains active wildcards.
102
In other words if "a*" matches a directory named "a*",
103
- "*" is matched literally so --max-depth is still effective.
103
+ "*" is matched literally so `--max-depth` is still effective.
104
105
--r::
106
---recursive::
105
+`-r`::
106
+`--recursive`::
107
Same as `--max-depth=-1`; this is the default.
108
109
---no-recursive::
109
+`--no-recursive`::
110
Same as `--max-depth=0`.
111
112
--w::
113
---word-regexp::
112
+`-w`::
113
+`--word-regexp`::
114
Match the pattern only at word boundary (either begin at the
115
beginning of a line, or preceded by a non-word character; end at
116
the end of a line or followed by a non-word character).
117
118
--v::
119
---invert-match::
118
+`-v`::
119
+`--invert-match`::
120
Select non-matching lines.
121
122
--h::
123
--H::
122
+`-h`::
123
+`-H`::
124
By default, the command shows the filename for each
125
match. `-h` option is used to suppress this output.
126
`-H` is there for completeness and does not do anything
127
except it overrides `-h` given earlier on the command
128
line.
129
130
---full-name::
130
+`--full-name`::
131
When run from a subdirectory, the command usually
132
outputs paths relative to the current directory. This
133
option forces paths to be output relative to the project
134
top directory.
135
136
--E::
137
---extended-regexp::
138
--G::
139
---basic-regexp::
136
+`-E`::
137
+`--extended-regexp`::
138
+`-G`::
139
+`--basic-regexp`::
140
Use POSIX extended/basic regexp for patterns. Default
141
is to use basic regexp.
142
143
--P::
144
---perl-regexp::
143
+`-P`::
144
+`--perl-regexp`::
145
Use Perl-compatible regular expressions for patterns.
146
+
147
Support for these types of regular expressions is an optional
148
compile-time dependency. If Git wasn't compiled with support for them
149
providing this option will cause it to die.
150
151
--F::
152
---fixed-strings::
151
+`-F`::
152
+`--fixed-strings`::
153
Use fixed strings for patterns (don't interpret pattern
154
as a regex).
155
156
--n::
157
---line-number::
156
+`-n`::
157
+`--line-number`::
158
Prefix the line number to matching lines.
159
160
---column::
160
+`--column`::
161
Prefix the 1-indexed byte-offset of the first match from the start of the
162
matching line.
163
164
--l::
165
---files-with-matches::
166
---name-only::
167
--L::
168
---files-without-match::
164
+`-l`::
165
+`--files-with-matches`::
166
+`--name-only`::
167
+`-L`::
168
+`--files-without-match`::
169
Instead of showing every matched line, show only the
170
names of files that contain (or do not contain) matches.
171
- For better compatibility with 'git diff', `--name-only` is a
171
+ For better compatibility with `git diff`, `--name-only` is a
172
synonym for `--files-with-matches`.
173
174
--O[<pager>]::
175
---open-files-in-pager[=<pager>]::
176
- Open the matching files in the pager (not the output of 'grep').
174
+`-O[<pager>]`::
175
+`--open-files-in-pager[=<pager>]`::
176
+ Open the matching files in the pager (not the output of `grep`).
177
If the pager happens to be "less" or "vi", and the user
178
specified only one pattern, the first file is positioned at
179
the first match automatically. The `pager` argument is
@@ -181,65 +181,65 @@ providing this option will cause it to die.
181
without a space. If `pager` is unspecified, the default pager
182
will be used (see `core.pager` in linkgit:git-config[1]).
183
184
--z::
185
---null::
184
+`-z`::
185
+`--null`::
186
Use \0 as the delimiter for pathnames in the output, and print
187
them verbatim. Without this option, pathnames with "unusual"
188
characters are quoted as explained for the configuration
189
variable `core.quotePath` (see linkgit:git-config[1]).
190
191
--o::
192
---only-matching::
191
+`-o`::
192
+`--only-matching`::
193
Print only the matched (non-empty) parts of a matching line, with each such
194
part on a separate output line.
195
196
--c::
197
---count::
196
+`-c`::
197
+`--count`::
198
Instead of showing every matched line, show the number of
199
lines that match.
200
201
---color[=<when>]::
201
+`--color[=<when>]`::
202
Show colored matches.
203
- The value must be always (the default), never, or auto.
203
+ The value must be `always` (the default), `never`, or `auto`.
204
205
---no-color::
205
+`--no-color`::
206
Turn off match highlighting, even when the configuration file
207
gives the default to color output.
208
Same as `--color=never`.
209
210
---break::
210
+`--break`::
211
Print an empty line between matches from different files.
212
213
---heading::
213
+`--heading`::
214
Show the filename above the matches in that file instead of
215
at the start of each shown line.
216
217
--p::
218
---show-function::
217
+`-p`::
218
+`--show-function`::
219
Show the preceding line that contains the function name of
220
the match, unless the matching line is a function name itself.
221
The name is determined in the same way as `git diff` works out
222
patch hunk headers (see 'Defining a custom hunk-header' in
223
linkgit:gitattributes[5]).
224
225
--<num>::
226
--C <num>::
227
---context <num>::
228
- Show <num> leading and trailing lines, and place a line
225
+`-<num>`::
226
+`-C <num>`::
227
+`--context <num>`::
228
+ Show _<num>_ leading and trailing lines, and place a line
229
containing `--` between contiguous groups of matches.
230
231
--A <num>::
232
---after-context <num>::
233
- Show <num> trailing lines, and place a line containing
231
+`-A <num>`::
232
+`--after-context <num>`::
233
+ Show _<num>_ trailing lines, and place a line containing
234
`--` between contiguous groups of matches.
235
236
--B <num>::
237
---before-context <num>::
238
- Show <num> leading lines, and place a line containing
236
+`-B <num>`::
237
+`--before-context <num>`::
238
+ Show _<num>_ leading lines, and place a line containing
239
`--` between contiguous groups of matches.
240
241
--W::
242
---function-context::
241
+`-W`::
242
+`--function-context`::
243
Show the surrounding text from the previous line containing a
244
function name up to the one before the next function name,
245
effectively showing the whole function in which the match was
@@ -247,22 +247,22 @@ providing this option will cause it to die.
247
`git diff` works out patch hunk headers (see 'Defining a
248
custom hunk-header' in linkgit:gitattributes[5]).
249
250
--m <num>::
251
---max-count <num>::
250
+`-m <num>`::
251
+`--max-count <num>`::
252
Limit the amount of matches per file. When using the `-v` or
253
`--invert-match` option, the search stops after the specified
254
number of non-matches. A value of -1 will return unlimited
255
results (the default). A value of 0 will exit immediately with
256
a non-zero status.
257
258
---threads <num>::
259
- Number of `grep` worker threads to use. See 'NOTES ON THREADS'
258
+`--threads <num>`::
259
+ Number of `grep` worker threads to use. See `NOTES ON THREADS`
260
and `grep.threads` in 'CONFIGURATION' for more information.
261
262
--f <file>::
263
- Read patterns from <file>, one per line.
262
+`-f <file>`::
263
+ Read patterns from _<file>_, one per line.
264
+
265
-Passing the pattern via <file> allows for providing a search pattern
265
+Passing the pattern via _<file>_ allows for providing a search pattern
266
containing a \0.
267
+
268
Not all pattern types support patterns containing \0. Git will error
@@ -279,44 +279,44 @@ In future versions we may learn to support patterns containing \0 for
279
more search backends, until then we'll die when the pattern type in
280
question doesn't support them.
281
282
--e::
282
+`-e`::
283
The next parameter is the pattern. This option has to be
284
used for patterns starting with `-` and should be used in
285
scripts passing user input to grep. Multiple patterns are
286
- combined by 'or'.
286
+ combined by `or`.
287
288
---and::
289
---or::
290
---not::
291
-( ... )::
288
+`--and`::
289
+`--or`::
290
+`--not`::
291
+`( ... )`::
292
Specify how multiple patterns are combined using Boolean
293
expressions. `--or` is the default operator. `--and` has
294
higher precedence than `--or`. `-e` has to be used for all
295
patterns.
296
297
---all-match::
297
+`--all-match`::
298
When giving multiple pattern expressions combined with `--or`,
299
this flag is specified to limit the match to files that
300
have lines to match all of them.
301
302
--q::
303
---quiet::
302
+`-q`::
303
+`--quiet`::
304
Do not output matched lines; instead, exit with status 0 when
305
there is a match and with non-zero status when there isn't.
306
307
-<tree>...::
307
+`<tree>...`::
308
Instead of searching tracked files in the working tree, search
309
blobs in the given trees.
310
311
-\--::
311
+`--`::
312
Signals the end of options; the rest of the parameters
313
- are <pathspec> limiters.
313
+ are _<pathspec>_ limiters.
314
315
-<pathspec>...::
315
+`<pathspec>...`::
316
If given, limit the search to paths matching at least one pattern.
317
- Both leading paths match and glob(7) patterns are supported.
317
+ Both leading paths match and `glob`(7) patterns are supported.
318
+
319
-For more details about the <pathspec> syntax, see the 'pathspec' entry
319
+For more details about the _<pathspec>_ syntax, see the `pathspec` entry
320
in linkgit:gitglossary[7].
321
322
EXAMPLES