1GIT-GREP(1) Git Manual GIT-GREP(1)
2
6 git-grep - Print lines matching a pattern
7
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 [--threads <num>]
24 [-f <file>] [-e] <pattern>
25 [--and|--or|--not|(|)|-e <pattern>...]
26 [--recurse-submodules] [--parent-basename <basename>]
27 [ [--[no-]exclude-standard] [--cached | --no-index | --untracked] | <tree>...]
28 [--] [<pathspec>...]
29
31 Look for specified patterns in the tracked files in the work tree,
32 blobs registered in the index file, or blobs in given tree objects.
33 Patterns are lists of one or more search expressions separated by
34 newline characters. An empty string as search expression matches all
35 lines.
36
38 --cached
39 Instead of searching tracked files in the working tree, search
40 blobs registered in the index file.
41 --no-index
43 Search files in the current directory that is not managed by Git.
44 --untracked
46 In addition to searching in the tracked files in the working tree,
47 search also in untracked files.
48 --no-exclude-standard
50 Also search in ignored files by not honoring the .gitignore
51 mechanism. Only useful with --untracked.
52 --exclude-standard
54 Do not pay attention to ignored files specified via the .gitignore
55 mechanism. Only useful when searching files in the current
56 directory with --no-index.
57 --recurse-submodules
59 Recursively search in each submodule that is active and checked out
60 in the repository. When used in combination with the <tree> option
61 the prefix of all submodule output will be the name of the parent
62 project’s <tree> object. This option has no effect if --no-index is
63 given.
64 -a, --text
66 Process binary files as if they were text.
67 --textconv
69 Honor textconv filter settings.
70 --no-textconv
72 Do not honor textconv filter settings. This is the default.
73 -i, --ignore-case
75 Ignore case differences between the patterns and the files.
76 -I
78 Don’t match the pattern in binary files.
79 --max-depth <depth>
81 For each <pathspec> given on command line, descend at most <depth>
82 levels of directories. A value of -1 means no limit. This option is
83 ignored if <pathspec> contains active wildcards. In other words if
84 "a*" matches a directory named "a*", "*" is matched literally so
85 --max-depth is still effective.
86 -r, --recursive
88 Same as --max-depth=-1; this is the default.
89 --no-recursive
91 Same as --max-depth=0.
92 -w, --word-regexp
94 Match the pattern only at word boundary (either begin at the
95 beginning of a line, or preceded by a non-word character; end at
96 the end of a line or followed by a non-word character).
97 -v, --invert-match
99 Select non-matching lines.
100 -h, -H
102 By default, the command shows the filename for each match. -h
103 option is used to suppress this output. -H is there for
104 completeness and does not do anything except it overrides -h given
105 earlier on the command line.
106 --full-name
108 When run from a subdirectory, the command usually outputs paths
109 relative to the current directory. This option forces paths to be
110 output relative to the project top directory.
111 -E, --extended-regexp, -G, --basic-regexp
113 Use POSIX extended/basic regexp for patterns. Default is to use
114 basic regexp.
115 -P, --perl-regexp
117 Use Perl-compatible regular expressions for patterns.
118 Support for these types of regular expressions is an optional
120 compile-time dependency. If Git wasn’t compiled with support for
121 them providing this option will cause it to die.
122 -F, --fixed-strings
124 Use fixed strings for patterns (don’t interpret pattern as a
125 regex).
126 -n, --line-number
128 Prefix the line number to matching lines.
129 --column
131 Prefix the 1-indexed byte-offset of the first match from the start
132 of the matching line.
133 -l, --files-with-matches, --name-only, -L, --files-without-match
135 Instead of showing every matched line, show only the names of files
136 that contain (or do not contain) matches. For better compatibility
137 with git diff, --name-only is a synonym for --files-with-matches.
138 -O[<pager>], --open-files-in-pager[=<pager>]
140 Open the matching files in the pager (not the output of grep). If
141 the pager happens to be "less" or "vi", and the user specified only
142 one pattern, the first file is positioned at the first match
143 automatically. The pager argument is optional; if specified, it
144 must be stuck to the option without a space. If pager is
145 unspecified, the default pager will be used (see core.pager in git-
146 config(1)).
147 -z, --null
149 Use \0 as the delimiter for pathnames in the output, and print them
150 verbatim. Without this option, pathnames with "unusual" characters
151 are quoted as explained for the configuration variable
152 core.quotePath (see git-config(1)).
153 -o, --only-matching
155 Print only the matched (non-empty) parts of a matching line, with
156 each such part on a separate output line.
157 -c, --count
159 Instead of showing every matched line, show the number of lines
160 that match.
161 --color[=<when>]
163 Show colored matches. The value must be always (the default),
164 never, or auto.
165 --no-color
167 Turn off match highlighting, even when the configuration file gives
168 the default to color output. Same as --color=never.
169 --break
171 Print an empty line between matches from different files.
172 --heading
174 Show the filename above the matches in that file instead of at the
175 start of each shown line.
176 -p, --show-function
178 Show the preceding line that contains the function name of the
179 match, unless the matching line is a function name itself. The name
180 is determined in the same way as git diff works out patch hunk
181 headers (see Defining a custom hunk-header in gitattributes(5)).
182 -<num>, -C <num>, --context <num>
184 Show <num> leading and trailing lines, and place a line containing
185 -- between contiguous groups of matches.
186 -A <num>, --after-context <num>
188 Show <num> trailing lines, and place a line containing -- between
189 contiguous groups of matches.
190 -B <num>, --before-context <num>
192 Show <num> leading lines, and place a line containing -- between
193 contiguous groups of matches.
194 -W, --function-context
196 Show the surrounding text from the previous line containing a
197 function name up to the one before the next function name,
198 effectively showing the whole function in which the match was
199 found. The function names are determined in the same way as git
200 diff works out patch hunk headers (see Defining a custom
201 hunk-header in gitattributes(5)).
202 --threads <num>
204 Number of grep worker threads to use. See grep.threads in
205 CONFIGURATION for more information.
206 -f <file>
208 Read patterns from <file>, one per line.
209 Passing the pattern via <file> allows for providing a search
211 pattern containing a \0.
212 Not all pattern types support patterns containing \0. Git will
214 error out if a given pattern type can’t support such a pattern. The
215 --perl-regexp pattern type when compiled against the PCRE v2
216 backend has the widest support for these types of patterns.
217 In versions of Git before 2.23.0 patterns containing \0 would be
219 silently considered fixed. This was never documented, there were
220 also odd and undocumented interactions between e.g. non-ASCII
221 patterns containing \0 and --ignore-case.
222 In future versions we may learn to support patterns containing \0
224 for more search backends, until then we’ll die when the pattern
225 type in question doesn’t support them.
226 -e
228 The next parameter is the pattern. This option has to be used for
229 patterns starting with - and should be used in scripts passing user
230 input to grep. Multiple patterns are combined by or.
231 --and, --or, --not, ( ... )
233 Specify how multiple patterns are combined using Boolean
234 expressions. --or is the default operator. --and has higher
235 precedence than --or. -e has to be used for all patterns.
236 --all-match
238 When giving multiple pattern expressions combined with --or, this
239 flag is specified to limit the match to files that have lines to
240 match all of them.
241 -q, --quiet
243 Do not output matched lines; instead, exit with status 0 when there
244 is a match and with non-zero status when there isn’t.
245 <tree>...
247 Instead of searching tracked files in the working tree, search
248 blobs in the given trees.
249 --
251 Signals the end of options; the rest of the parameters are
252 <pathspec> limiters.
253 <pathspec>...
255 If given, limit the search to paths matching at least one pattern.
256 Both leading paths match and glob(7) patterns are supported.
257 For more details about the <pathspec> syntax, see the pathspec
259 entry in gitglossary(7).
260
262 git grep 'time_t' -- '*.[ch]'
263 Looks for time_t in all tracked .c and .h files in the working
264 directory and its subdirectories.
265 git grep -e '#define' --and \( -e MAX_PATH -e PATH_MAX \)
267 Looks for a line that has #define and either MAX_PATH or PATH_MAX.
268 git grep --all-match -e NODE -e Unexpected
270 Looks for a line that has NODE or Unexpected in files that have
271 lines that match both.
272 git grep solution -- :^Documentation
274 Looks for solution, excluding files in Documentation.
275
277 The --threads option (and the grep.threads configuration) will be
278 ignored when --open-files-in-pager is used, forcing a single-threaded
279 execution.
280 When grepping the object store (with --cached or giving tree objects),
282 running with multiple threads might perform slower than single threaded
283 if --textconv is given and there’re too many text conversions. So if
284 you experience low performance in this case, it might be desirable to
285 use --threads=1.
286
288 grep.lineNumber
289 If set to true, enable -n option by default.
290 grep.column
292 If set to true, enable the --column option by default.
293 grep.patternType
295 Set the default matching behavior. Using a value of basic,
296 extended, fixed, or perl will enable the --basic-regexp,
297 --extended-regexp, --fixed-strings, or --perl-regexp option
298 accordingly, while the value default will return to the default
299 matching behavior.
300 grep.extendedRegexp
302 If set to true, enable --extended-regexp option by default. This
303 option is ignored when the grep.patternType option is set to a
304 value other than default.
305 grep.threads
307 Number of grep worker threads to use. If unset (or set to 0), Git
308 will use as many threads as the number of logical cores available.
309 grep.fullName
311 If set to true, enable --full-name option by default.
312 grep.fallbackToNoIndex
314 If set to true, fall back to git grep --no-index if git grep is
315 executed outside of a git repository. Defaults to false.
316
318 Part of the git(1) suite
319Git 2.33.1 2021-10-12 GIT-GREP(1)