rebase: add --quit to cleanup rebase, leave everything else untouched
[git.git] / Documentation / git-grep.txt
blobcb0f6cf6782c87d7a5b08e2b75de5b4ecb2969f9
1 git-grep(1)
2 ===========
4 NAME
5 ----
6 git-grep - Print lines matching a pattern
9 SYNOPSIS
10 --------
11 [verse]
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]
16            [-F | --fixed-strings] [-n | --line-number]
17            [-l | --files-with-matches] [-L | --files-without-match]
18            [(-O | --open-files-in-pager) [<pager>]]
19            [-z | --null]
20            [-c | --count] [--all-match] [-q | --quiet]
21            [--max-depth <depth>]
22            [--color[=<when>] | --no-color]
23            [--break] [--heading] [-p | --show-function]
24            [-A <post-context>] [-B <pre-context>] [-C <context>]
25            [-W | --function-context]
26            [--threads <num>]
27            [-f <file>] [-e] <pattern>
28            [--and|--or|--not|(|)|-e <pattern>...]
29            [ [--[no-]exclude-standard] [--cached | --no-index | --untracked] | <tree>...]
30            [--] [<pathspec>...]
32 DESCRIPTION
33 -----------
34 Look for specified patterns in the tracked files in the work tree, blobs
35 registered in the index file, or blobs in given tree objects.  Patterns
36 are lists of one or more search expressions separated by newline
37 characters.  An empty string as search expression matches all lines.
40 CONFIGURATION
41 -------------
43 grep.lineNumber::
44         If set to true, enable '-n' option by default.
46 grep.patternType::
47         Set the default matching behavior. Using a value of 'basic', 'extended',
48         'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp',
49         '--fixed-strings', or '--perl-regexp' option accordingly, while the
50         value 'default' will return to the default matching behavior.
52 grep.extendedRegexp::
53         If set to true, enable '--extended-regexp' option by default. This
54         option is ignored when the 'grep.patternType' option is set to a value
55         other than 'default'.
57 grep.threads::
58         Number of grep worker threads to use.  If unset (or set to 0),
59         8 threads are used by default (for now).
61 grep.fullName::
62         If set to true, enable '--full-name' option by default.
64 grep.fallbackToNoIndex::
65         If set to true, fall back to git grep --no-index if git grep
66         is executed outside of a git repository.  Defaults to false.
69 OPTIONS
70 -------
71 --cached::
72         Instead of searching tracked files in the working tree, search
73         blobs registered in the index file.
75 --no-index::
76         Search files in the current directory that is not managed by Git.
78 --untracked::
79         In addition to searching in the tracked files in the working
80         tree, search also in untracked files.
82 --no-exclude-standard::
83         Also search in ignored files by not honoring the `.gitignore`
84         mechanism. Only useful with `--untracked`.
86 --exclude-standard::
87         Do not pay attention to ignored files specified via the `.gitignore`
88         mechanism.  Only useful when searching files in the current directory
89         with `--no-index`.
91 -a::
92 --text::
93         Process binary files as if they were text.
95 --textconv::
96         Honor textconv filter settings.
98 --no-textconv::
99         Do not honor textconv filter settings.
100         This is the default.
102 -i::
103 --ignore-case::
104         Ignore case differences between the patterns and the
105         files.
107 -I::
108         Don't match the pattern in binary files.
110 --max-depth <depth>::
111         For each <pathspec> given on command line, descend at most <depth>
112         levels of directories. A negative value means no limit.
113         This option is ignored if <pathspec> contains active wildcards.
114         In other words if "a*" matches a directory named "a*",
115         "*" is matched literally so --max-depth is still effective.
117 -w::
118 --word-regexp::
119         Match the pattern only at word boundary (either begin at the
120         beginning of a line, or preceded by a non-word character; end at
121         the end of a line or followed by a non-word character).
123 -v::
124 --invert-match::
125         Select non-matching lines.
127 -h::
128 -H::
129         By default, the command shows the filename for each
130         match.  `-h` option is used to suppress this output.
131         `-H` is there for completeness and does not do anything
132         except it overrides `-h` given earlier on the command
133         line.
135 --full-name::
136         When run from a subdirectory, the command usually
137         outputs paths relative to the current directory.  This
138         option forces paths to be output relative to the project
139         top directory.
141 -E::
142 --extended-regexp::
143 -G::
144 --basic-regexp::
145         Use POSIX extended/basic regexp for patterns.  Default
146         is to use basic regexp.
148 -P::
149 --perl-regexp::
150         Use Perl-compatible regexp for patterns. Requires libpcre to be
151         compiled in.
153 -F::
154 --fixed-strings::
155         Use fixed strings for patterns (don't interpret pattern
156         as a regex).
158 -n::
159 --line-number::
160         Prefix the line number to matching lines.
162 -l::
163 --files-with-matches::
164 --name-only::
165 -L::
166 --files-without-match::
167         Instead of showing every matched line, show only the
168         names of files that contain (or do not contain) matches.
169         For better compatibility with 'git diff', `--name-only` is a
170         synonym for `--files-with-matches`.
172 -O[<pager>]::
173 --open-files-in-pager[=<pager>]::
174         Open the matching files in the pager (not the output of 'grep').
175         If the pager happens to be "less" or "vi", and the user
176         specified only one pattern, the first file is positioned at
177         the first match automatically. The `pager` argument is
178         optional; if specified, it must be stuck to the option
179         without a space. If `pager` is unspecified, the default pager
180         will be used (see `core.pager` in linkgit:git-config[1]).
182 -z::
183 --null::
184         Output \0 instead of the character that normally follows a
185         file name.
187 -c::
188 --count::
189         Instead of showing every matched line, show the number of
190         lines that match.
192 --color[=<when>]::
193         Show colored matches.
194         The value must be always (the default), never, or auto.
196 --no-color::
197         Turn off match highlighting, even when the configuration file
198         gives the default to color output.
199         Same as `--color=never`.
201 --break::
202         Print an empty line between matches from different files.
204 --heading::
205         Show the filename above the matches in that file instead of
206         at the start of each shown line.
208 -p::
209 --show-function::
210         Show the preceding line that contains the function name of
211         the match, unless the matching line is a function name itself.
212         The name is determined in the same way as 'git diff' works out
213         patch hunk headers (see 'Defining a custom hunk-header' in
214         linkgit:gitattributes[5]).
216 -<num>::
217 -C <num>::
218 --context <num>::
219         Show <num> leading and trailing lines, and place a line
220         containing `--` between contiguous groups of matches.
222 -A <num>::
223 --after-context <num>::
224         Show <num> trailing lines, and place a line containing
225         `--` between contiguous groups of matches.
227 -B <num>::
228 --before-context <num>::
229         Show <num> leading lines, and place a line containing
230         `--` between contiguous groups of matches.
232 -W::
233 --function-context::
234         Show the surrounding text from the previous line containing a
235         function name up to the one before the next function name,
236         effectively showing the whole function in which the match was
237         found.
239 --threads <num>::
240         Number of grep worker threads to use.
241         See `grep.threads` in 'CONFIGURATION' for more information.
243 -f <file>::
244         Read patterns from <file>, one per line.
246 -e::
247         The next parameter is the pattern. This option has to be
248         used for patterns starting with `-` and should be used in
249         scripts passing user input to grep.  Multiple patterns are
250         combined by 'or'.
252 --and::
253 --or::
254 --not::
255 ( ... )::
256         Specify how multiple patterns are combined using Boolean
257         expressions.  `--or` is the default operator.  `--and` has
258         higher precedence than `--or`.  `-e` has to be used for all
259         patterns.
261 --all-match::
262         When giving multiple pattern expressions combined with `--or`,
263         this flag is specified to limit the match to files that
264         have lines to match all of them.
266 -q::
267 --quiet::
268         Do not output matched lines; instead, exit with status 0 when
269         there is a match and with non-zero status when there isn't.
271 <tree>...::
272         Instead of searching tracked files in the working tree, search
273         blobs in the given trees.
275 \--::
276         Signals the end of options; the rest of the parameters
277         are <pathspec> limiters.
279 <pathspec>...::
280         If given, limit the search to paths matching at least one pattern.
281         Both leading paths match and glob(7) patterns are supported.
283 Examples
284 --------
286 `git grep 'time_t' -- '*.[ch]'`::
287         Looks for `time_t` in all tracked .c and .h files in the working
288         directory and its subdirectories.
290 `git grep -e '#define' --and \( -e MAX_PATH -e PATH_MAX \)`::
291         Looks for a line that has `#define` and either `MAX_PATH` or
292         `PATH_MAX`.
294 `git grep --all-match -e NODE -e Unexpected`::
295         Looks for a line that has `NODE` or `Unexpected` in
296         files that have lines that match both.
300 Part of the linkgit:git[1] suite