Merge branch 'maint-1.7.3' into maint
[git/git.git] / Documentation / git-grep.txt
1 git-grep(1)
2 ===========
3
4 NAME
5 ----
6 git-grep - Print lines matching a pattern
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git grep' [-a | --text] [-I] [-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 [-A <post-context>] [-B <pre-context>] [-C <context>]
24 [-f <file>] [-e] <pattern>
25 [--and|--or|--not|(|)|-e <pattern>...]
26 [--cached | --no-index | <tree>...]
27 [--] [<pathspec>...]
28
29 DESCRIPTION
30 -----------
31 Look for specified patterns in the tracked files in the work tree, blobs
32 registered in the index file, or blobs in given tree objects.
33
34
35 CONFIGURATION
36 -------------
37
38 grep.lineNumber::
39 If set to true, enable '-n' option by default.
40
41 grep.extendedRegexp::
42 If set to true, enable '--extended-regexp' option by default.
43
44
45 OPTIONS
46 -------
47 --cached::
48 Instead of searching tracked files in the working tree, search
49 blobs registered in the index file.
50
51 --no-index::
52 Search files in the current directory, not just those tracked by git.
53
54 -a::
55 --text::
56 Process binary files as if they were text.
57
58 -i::
59 --ignore-case::
60 Ignore case differences between the patterns and the
61 files.
62
63 -I::
64 Don't match the pattern in binary files.
65
66 --max-depth <depth>::
67 For each <pathspec> given on command line, descend at most <depth>
68 levels of directories. A negative value means no limit.
69
70 -w::
71 --word-regexp::
72 Match the pattern only at word boundary (either begin at the
73 beginning of a line, or preceded by a non-word character; end at
74 the end of a line or followed by a non-word character).
75
76 -v::
77 --invert-match::
78 Select non-matching lines.
79
80 -h::
81 -H::
82 By default, the command shows the filename for each
83 match. `-h` option is used to suppress this output.
84 `-H` is there for completeness and does not do anything
85 except it overrides `-h` given earlier on the command
86 line.
87
88 --full-name::
89 When run from a subdirectory, the command usually
90 outputs paths relative to the current directory. This
91 option forces paths to be output relative to the project
92 top directory.
93
94 -E::
95 --extended-regexp::
96 -G::
97 --basic-regexp::
98 Use POSIX extended/basic regexp for patterns. Default
99 is to use basic regexp.
100
101 -P::
102 --perl-regexp::
103 Use Perl-compatible regexp for patterns. Requires libpcre to be
104 compiled in.
105
106 -F::
107 --fixed-strings::
108 Use fixed strings for patterns (don't interpret pattern
109 as a regex).
110
111 -n::
112 --line-number::
113 Prefix the line number to matching lines.
114
115 -l::
116 --files-with-matches::
117 --name-only::
118 -L::
119 --files-without-match::
120 Instead of showing every matched line, show only the
121 names of files that contain (or do not contain) matches.
122 For better compatibility with 'git diff', `--name-only` is a
123 synonym for `--files-with-matches`.
124
125 -O [<pager>]::
126 --open-files-in-pager [<pager>]::
127 Open the matching files in the pager (not the output of 'grep').
128 If the pager happens to be "less" or "vi", and the user
129 specified only one pattern, the first file is positioned at
130 the first match automatically.
131
132 -z::
133 --null::
134 Output \0 instead of the character that normally follows a
135 file name.
136
137 -c::
138 --count::
139 Instead of showing every matched line, show the number of
140 lines that match.
141
142 --color[=<when>]::
143 Show colored matches.
144 The value must be always (the default), never, or auto.
145
146 --no-color::
147 Turn off match highlighting, even when the configuration file
148 gives the default to color output.
149 Same as `--color=never`.
150
151 --break::
152 Print an empty line between matches from different files.
153
154 --heading::
155 Show the filename above the matches in that file instead of
156 at the start of each shown line.
157
158 -p::
159 --show-function::
160 Show the preceding line that contains the function name of
161 the match, unless the matching line is a function name itself.
162 The name is determined in the same way as 'git diff' works out
163 patch hunk headers (see 'Defining a custom hunk-header' in
164 linkgit:gitattributes[5]).
165
166 -<num>::
167 -C <num>::
168 --context <num>::
169 Show <num> leading and trailing lines, and place a line
170 containing `--` between contiguous groups of matches.
171
172 -A <num>::
173 --after-context <num>::
174 Show <num> trailing lines, and place a line containing
175 `--` between contiguous groups of matches.
176
177 -B <num>::
178 --before-context <num>::
179 Show <num> leading lines, and place a line containing
180 `--` between contiguous groups of matches.
181
182 -W::
183 --function-context::
184 Show the surrounding text from the previous line containing a
185 function name up to the one before the next function name,
186 effectively showing the whole function in which the match was
187 found.
188
189 -f <file>::
190 Read patterns from <file>, one per line.
191
192 -e::
193 The next parameter is the pattern. This option has to be
194 used for patterns starting with `-` and should be used in
195 scripts passing user input to grep. Multiple patterns are
196 combined by 'or'.
197
198 --and::
199 --or::
200 --not::
201 ( ... )::
202 Specify how multiple patterns are combined using Boolean
203 expressions. `--or` is the default operator. `--and` has
204 higher precedence than `--or`. `-e` has to be used for all
205 patterns.
206
207 --all-match::
208 When giving multiple pattern expressions combined with `--or`,
209 this flag is specified to limit the match to files that
210 have lines to match all of them.
211
212 -q::
213 --quiet::
214 Do not output matched lines; instead, exit with status 0 when
215 there is a match and with non-zero status when there isn't.
216
217 <tree>...::
218 Instead of searching tracked files in the working tree, search
219 blobs in the given trees.
220
221 \--::
222 Signals the end of options; the rest of the parameters
223 are <pathspec> limiters.
224
225 <pathspec>...::
226 If given, limit the search to paths matching at least one pattern.
227 Both leading paths match and glob(7) patterns are supported.
228
229 Examples
230 --------
231
232 `git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}`::
233 Looks for `time_t` in all tracked .c and .h files in the working
234 directory and its subdirectories.
235
236 `git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \)`::
237 Looks for a line that has `#define` and either `MAX_PATH` or
238 `PATH_MAX`.
239
240 `git grep --all-match -e NODE -e Unexpected`::
241 Looks for a line that has `NODE` or `Unexpected` in
242 files that have lines that match both.
243
244 GIT
245 ---
246 Part of the linkgit:git[1] suite