1GIT-GREP(1)                       Git Manual                       GIT-GREP(1)
2
3
4

NAME

6       git-grep - Print lines matching a pattern
7

SYNOPSIS

9       git grep [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp]
10                  [-v | --invert-match] [-h|-H] [--full-name]
11                  [-E | --extended-regexp] [-G | --basic-regexp]
12                  [-P | --perl-regexp]
13                  [-F | --fixed-strings] [-n | --line-number] [--column]
14                  [-l | --files-with-matches] [-L | --files-without-match]
15                  [(-O | --open-files-in-pager) [<pager>]]
16                  [-z | --null]
17                  [ -o | --only-matching ] [-c | --count] [--all-match] [-q | --quiet]
18                  [--max-depth <depth>] [--[no-]recursive]
19                  [--color[=<when>] | --no-color]
20                  [--break] [--heading] [-p | --show-function]
21                  [-A <post-context>] [-B <pre-context>] [-C <context>]
22                  [-W | --function-context]
23                  [(-m | --max-count) <num>]
24                  [--threads <num>]
25                  [-f <file>] [-e] <pattern>
26                  [--and|--or|--not|(|)|-e <pattern>...]
27                  [--recurse-submodules] [--parent-basename <basename>]
28                  [ [--[no-]exclude-standard] [--cached | --no-index | --untracked] | <tree>...]
29                  [--] [<pathspec>...]
30

DESCRIPTION

32       Look for specified patterns in the tracked files in the work tree,
33       blobs registered in the index file, or blobs in given tree objects.
34       Patterns are lists of one or more search expressions separated by
35       newline characters. An empty string as search expression matches all
36       lines.
37

OPTIONS

39       --cached
40           Instead of searching tracked files in the working tree, search
41           blobs registered in the index file.
42
43       --no-index
44           Search files in the current directory that is not managed by Git.
45
46       --untracked
47           In addition to searching in the tracked files in the working tree,
48           search also in untracked files.
49
50       --no-exclude-standard
51           Also search in ignored files by not honoring the .gitignore
52           mechanism. Only useful with --untracked.
53
54       --exclude-standard
55           Do not pay attention to ignored files specified via the .gitignore
56           mechanism. Only useful when searching files in the current
57           directory with --no-index.
58
59       --recurse-submodules
60           Recursively search in each submodule that is active and checked out
61           in the repository. When used in combination with the <tree> option
62           the prefix of all submodule output will be the name of the parent
63           project’s <tree> object. This option has no effect if --no-index is
64           given.
65
66       -a, --text
67           Process binary files as if they were text.
68
69       --textconv
70           Honor textconv filter settings.
71
72       --no-textconv
73           Do not honor textconv filter settings. This is the default.
74
75       -i, --ignore-case
76           Ignore case differences between the patterns and the files.
77
78       -I
79           Don’t match the pattern in binary files.
80
81       --max-depth <depth>
82           For each <pathspec> given on command line, descend at most <depth>
83           levels of directories. A value of -1 means no limit. This option is
84           ignored if <pathspec> contains active wildcards. In other words if
85           "a*" matches a directory named "a*", "*" is matched literally so
86           --max-depth is still effective.
87
88       -r, --recursive
89           Same as --max-depth=-1; this is the default.
90
91       --no-recursive
92           Same as --max-depth=0.
93
94       -w, --word-regexp
95           Match the pattern only at word boundary (either begin at the
96           beginning of a line, or preceded by a non-word character; end at
97           the end of a line or followed by a non-word character).
98
99       -v, --invert-match
100           Select non-matching lines.
101
102       -h, -H
103           By default, the command shows the filename for each match.  -h
104           option is used to suppress this output.  -H is there for
105           completeness and does not do anything except it overrides -h given
106           earlier on the command line.
107
108       --full-name
109           When run from a subdirectory, the command usually outputs paths
110           relative to the current directory. This option forces paths to be
111           output relative to the project top directory.
112
113       -E, --extended-regexp, -G, --basic-regexp
114           Use POSIX extended/basic regexp for patterns. Default is to use
115           basic regexp.
116
117       -P, --perl-regexp
118           Use Perl-compatible regular expressions for patterns.
119
120           Support for these types of regular expressions is an optional
121           compile-time dependency. If Git wasn’t compiled with support for
122           them providing this option will cause it to die.
123
124       -F, --fixed-strings
125           Use fixed strings for patterns (don’t interpret pattern as a
126           regex).
127
128       -n, --line-number
129           Prefix the line number to matching lines.
130
131       --column
132           Prefix the 1-indexed byte-offset of the first match from the start
133           of the matching line.
134
135       -l, --files-with-matches, --name-only, -L, --files-without-match
136           Instead of showing every matched line, show only the names of files
137           that contain (or do not contain) matches. For better compatibility
138           with git diff, --name-only is a synonym for --files-with-matches.
139
140       -O[<pager>], --open-files-in-pager[=<pager>]
141           Open the matching files in the pager (not the output of grep). If
142           the pager happens to be "less" or "vi", and the user specified only
143           one pattern, the first file is positioned at the first match
144           automatically. The pager argument is optional; if specified, it
145           must be stuck to the option without a space. If pager is
146           unspecified, the default pager will be used (see core.pager in git-
147           config(1)).
148
149       -z, --null
150           Use \0 as the delimiter for pathnames in the output, and print them
151           verbatim. Without this option, pathnames with "unusual" characters
152           are quoted as explained for the configuration variable
153           core.quotePath (see git-config(1)).
154
155       -o, --only-matching
156           Print only the matched (non-empty) parts of a matching line, with
157           each such part on a separate output line.
158
159       -c, --count
160           Instead of showing every matched line, show the number of lines
161           that match.
162
163       --color[=<when>]
164           Show colored matches. The value must be always (the default),
165           never, or auto.
166
167       --no-color
168           Turn off match highlighting, even when the configuration file gives
169           the default to color output. Same as --color=never.
170
171       --break
172           Print an empty line between matches from different files.
173
174       --heading
175           Show the filename above the matches in that file instead of at the
176           start of each shown line.
177
178       -p, --show-function
179           Show the preceding line that contains the function name of the
180           match, unless the matching line is a function name itself. The name
181           is determined in the same way as git diff works out patch hunk
182           headers (see Defining a custom hunk-header in gitattributes(5)).
183
184       -<num>, -C <num>, --context <num>
185           Show <num> leading and trailing lines, and place a line containing
186           -- between contiguous groups of matches.
187
188       -A <num>, --after-context <num>
189           Show <num> trailing lines, and place a line containing -- between
190           contiguous groups of matches.
191
192       -B <num>, --before-context <num>
193           Show <num> leading lines, and place a line containing -- between
194           contiguous groups of matches.
195
196       -W, --function-context
197           Show the surrounding text from the previous line containing a
198           function name up to the one before the next function name,
199           effectively showing the whole function in which the match was
200           found. The function names are determined in the same way as git
201           diff works out patch hunk headers (see Defining a custom
202           hunk-header in gitattributes(5)).
203
204       -m <num>, --max-count <num>
205           Limit the amount of matches per file. When using the -v or
206           --invert-match option, the search stops after the specified number
207           of non-matches. A value of -1 will return unlimited results (the
208           default). A value of 0 will exit immediately with a non-zero
209           status.
210
211       --threads <num>
212           Number of grep worker threads to use. See grep.threads in
213           CONFIGURATION for more information.
214
215       -f <file>
216           Read patterns from <file>, one per line.
217
218           Passing the pattern via <file> allows for providing a search
219           pattern containing a \0.
220
221           Not all pattern types support patterns containing \0. Git will
222           error out if a given pattern type can’t support such a pattern. The
223           --perl-regexp pattern type when compiled against the PCRE v2
224           backend has the widest support for these types of patterns.
225
226           In versions of Git before 2.23.0 patterns containing \0 would be
227           silently considered fixed. This was never documented, there were
228           also odd and undocumented interactions between e.g. non-ASCII
229           patterns containing \0 and --ignore-case.
230
231           In future versions we may learn to support patterns containing \0
232           for more search backends, until then we’ll die when the pattern
233           type in question doesn’t support them.
234
235       -e
236           The next parameter is the pattern. This option has to be used for
237           patterns starting with - and should be used in scripts passing user
238           input to grep. Multiple patterns are combined by or.
239
240       --and, --or, --not, ( ... )
241           Specify how multiple patterns are combined using Boolean
242           expressions.  --or is the default operator.  --and has higher
243           precedence than --or.  -e has to be used for all patterns.
244
245       --all-match
246           When giving multiple pattern expressions combined with --or, this
247           flag is specified to limit the match to files that have lines to
248           match all of them.
249
250       -q, --quiet
251           Do not output matched lines; instead, exit with status 0 when there
252           is a match and with non-zero status when there isn’t.
253
254       <tree>...
255           Instead of searching tracked files in the working tree, search
256           blobs in the given trees.
257
258       --
259           Signals the end of options; the rest of the parameters are
260           <pathspec> limiters.
261
262       <pathspec>...
263           If given, limit the search to paths matching at least one pattern.
264           Both leading paths match and glob(7) patterns are supported.
265
266           For more details about the <pathspec> syntax, see the pathspec
267           entry in gitglossary(7).
268

EXAMPLES

270       git grep 'time_t' -- '*.[ch]'
271           Looks for time_t in all tracked .c and .h files in the working
272           directory and its subdirectories.
273
274       git grep -e '#define' --and \( -e MAX_PATH -e PATH_MAX \)
275           Looks for a line that has #define and either MAX_PATH or PATH_MAX.
276
277       git grep --all-match -e NODE -e Unexpected
278           Looks for a line that has NODE or Unexpected in files that have
279           lines that match both.
280
281       git grep solution -- :^Documentation
282           Looks for solution, excluding files in Documentation.
283

NOTES ON THREADS

285       The --threads option (and the grep.threads configuration) will be
286       ignored when --open-files-in-pager is used, forcing a single-threaded
287       execution.
288
289       When grepping the object store (with --cached or giving tree objects),
290       running with multiple threads might perform slower than single threaded
291       if --textconv is given and there are too many text conversions. So if
292       you experience low performance in this case, it might be desirable to
293       use --threads=1.
294

CONFIGURATION

296       Everything below this line in this section is selectively included from
297       the git-config(1) documentation. The content is the same as what’s
298       found there:
299
300       grep.lineNumber
301           If set to true, enable -n option by default.
302
303       grep.column
304           If set to true, enable the --column option by default.
305
306       grep.patternType
307           Set the default matching behavior. Using a value of basic,
308           extended, fixed, or perl will enable the --basic-regexp,
309           --extended-regexp, --fixed-strings, or --perl-regexp option
310           accordingly, while the value default will use the
311           grep.extendedRegexp option to choose between basic and extended.
312
313       grep.extendedRegexp
314           If set to true, enable --extended-regexp option by default. This
315           option is ignored when the grep.patternType option is set to a
316           value other than default.
317
318       grep.threads
319           Number of grep worker threads to use. If unset (or set to 0), Git
320           will use as many threads as the number of logical cores available.
321
322       grep.fullName
323           If set to true, enable --full-name option by default.
324
325       grep.fallbackToNoIndex
326           If set to true, fall back to git grep --no-index if git grep is
327           executed outside of a git repository. Defaults to false.
328

GIT

330       Part of the git(1) suite
331
332
333
334Git 2.43.0                        11/20/2023                       GIT-GREP(1)
Impressum