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