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