Code

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