| 1 | git-grep(1) |
| 2 | =========== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-grep - Print lines matching a pattern |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [synopsis] |
| 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] [--column] |
| 17 | [-l | --files-with-matches] [-L | --files-without-match] |
| 18 | [(-O | --open-files-in-pager) [<pager>]] |
| 19 | [-z | --null] |
| 20 | [ -o | --only-matching ] [-c | --count] [--all-match] [-q | --quiet] |
| 21 | [--max-depth <depth>] [--[no-]recursive] |
| 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 | [(-m | --max-count) <num>] |
| 27 | [--threads <num>] |
| 28 | [-f <file>] [-e] <pattern> |
| 29 | [--and|--or|--not|(|)|-e <pattern>...] |
| 30 | [--recurse-submodules] [--parent-basename <basename>] |
| 31 | [ [--[no-]exclude-standard] [--cached | --untracked | --no-index] | <tree>...] |
| 32 | [--] [<pathspec>...] |
| 33 | |
| 34 | DESCRIPTION |
| 35 | ----------- |
| 36 | Look for specified patterns in the tracked files in the work tree, blobs |
| 37 | registered in the index file, or blobs in given tree objects. Patterns |
| 38 | are lists of one or more search expressions separated by newline |
| 39 | characters. An empty string as search expression matches all lines. |
| 40 | |
| 41 | |
| 42 | OPTIONS |
| 43 | ------- |
| 44 | `--cached`:: |
| 45 | Instead of searching tracked files in the working tree, search |
| 46 | blobs registered in the index file. |
| 47 | |
| 48 | `--untracked`:: |
| 49 | In addition to searching in the tracked files in the working |
| 50 | tree, search also in untracked files. |
| 51 | |
| 52 | `--no-index`:: |
| 53 | Search files in the current directory that is not managed by Git, |
| 54 | or by ignoring that the current directory is managed by Git. This |
| 55 | is rather similar to running the regular `grep`(1) utility with its |
| 56 | `-r` option specified, but with some additional benefits, such as |
| 57 | using pathspec patterns to limit paths; see the `pathspec` entry |
| 58 | in linkgit:gitglossary[7] for more information. |
| 59 | + |
| 60 | This option cannot be used together with `--cached` or `--untracked`. |
| 61 | See also `grep.fallbackToNoIndex` in 'CONFIGURATION' below. |
| 62 | |
| 63 | `--no-exclude-standard`:: |
| 64 | Also search in ignored files by not honoring the `.gitignore` |
| 65 | mechanism. Only useful with `--untracked`. |
| 66 | |
| 67 | `--exclude-standard`:: |
| 68 | Do not pay attention to ignored files specified via the `.gitignore` |
| 69 | mechanism. Only useful when searching files in the current directory |
| 70 | with `--no-index`. |
| 71 | |
| 72 | `--recurse-submodules`:: |
| 73 | Recursively search in each submodule that is active and |
| 74 | checked out in the repository. When used in combination with the |
| 75 | _<tree>_ option the prefix of all submodule output will be the name of |
| 76 | the parent project's _<tree>_ object. This option cannot be used together |
| 77 | with `--untracked`, and it has no effect if `--no-index` is specified. |
| 78 | |
| 79 | `-a`:: |
| 80 | `--text`:: |
| 81 | Process binary files as if they were text. |
| 82 | |
| 83 | `--textconv`:: |
| 84 | Honor textconv filter settings. |
| 85 | |
| 86 | `--no-textconv`:: |
| 87 | Do not honor textconv filter settings. |
| 88 | This is the default. |
| 89 | |
| 90 | `-i`:: |
| 91 | `--ignore-case`:: |
| 92 | Ignore case differences between the patterns and the |
| 93 | files. |
| 94 | |
| 95 | `-I`:: |
| 96 | Don't match the pattern in binary files. |
| 97 | |
| 98 | `--max-depth <depth>`:: |
| 99 | For each _<pathspec>_ given on command line, descend at most _<depth>_ |
| 100 | levels of directories. A value of -1 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. |
| 104 | |
| 105 | `-r`:: |
| 106 | `--recursive`:: |
| 107 | Same as `--max-depth=-1`; this is the default. |
| 108 | |
| 109 | `--no-recursive`:: |
| 110 | Same as `--max-depth=0`. |
| 111 | |
| 112 | `-w`:: |
| 113 | `--word-regexp`:: |
| 114 | Match the pattern only at word boundary (either begin at the |
| 115 | beginning of a line, or preceded by a non-word character; end at |
| 116 | the end of a line or followed by a non-word character). |
| 117 | |
| 118 | `-v`:: |
| 119 | `--invert-match`:: |
| 120 | Select non-matching lines. |
| 121 | |
| 122 | `-h`:: |
| 123 | `-H`:: |
| 124 | By default, the command shows the filename for each |
| 125 | match. `-h` option is used to suppress this output. |
| 126 | `-H` is there for completeness and does not do anything |
| 127 | except it overrides `-h` given earlier on the command |
| 128 | line. |
| 129 | |
| 130 | `--full-name`:: |
| 131 | When run from a subdirectory, the command usually |
| 132 | outputs paths relative to the current directory. This |
| 133 | option forces paths to be output relative to the project |
| 134 | top directory. |
| 135 | |
| 136 | `-E`:: |
| 137 | `--extended-regexp`:: |
| 138 | `-G`:: |
| 139 | `--basic-regexp`:: |
| 140 | Use POSIX extended/basic regexp for patterns. Default |
| 141 | is to use basic regexp. |
| 142 | |
| 143 | `-P`:: |
| 144 | `--perl-regexp`:: |
| 145 | Use Perl-compatible regular expressions for patterns. |
| 146 | + |
| 147 | Support for these types of regular expressions is an optional |
| 148 | compile-time dependency. If Git wasn't compiled with support for them |
| 149 | providing this option will cause it to die. |
| 150 | |
| 151 | `-F`:: |
| 152 | `--fixed-strings`:: |
| 153 | Use fixed strings for patterns (don't interpret pattern |
| 154 | as a regex). |
| 155 | |
| 156 | `-n`:: |
| 157 | `--line-number`:: |
| 158 | Prefix the line number to matching lines. |
| 159 | |
| 160 | `--column`:: |
| 161 | Prefix the 1-indexed byte-offset of the first match from the start of the |
| 162 | matching line. |
| 163 | |
| 164 | `-l`:: |
| 165 | `--files-with-matches`:: |
| 166 | `--name-only`:: |
| 167 | `-L`:: |
| 168 | `--files-without-match`:: |
| 169 | Instead of showing every matched line, show only the |
| 170 | names of files that contain (or do not contain) matches. |
| 171 | For better compatibility with `git diff`, `--name-only` is a |
| 172 | synonym for `--files-with-matches`. |
| 173 | |
| 174 | `-O[<pager>]`:: |
| 175 | `--open-files-in-pager[=<pager>]`:: |
| 176 | Open the matching files in the pager (not the output of `grep`). |
| 177 | If the pager happens to be "less" or "vi", and the user |
| 178 | specified only one pattern, the first file is positioned at |
| 179 | the first match automatically. The `pager` argument is |
| 180 | optional; if specified, it must be stuck to the option |
| 181 | without a space. If `pager` is unspecified, the default pager |
| 182 | will be used (see `core.pager` in linkgit:git-config[1]). |
| 183 | |
| 184 | `-z`:: |
| 185 | `--null`:: |
| 186 | Use \0 as the delimiter for pathnames in the output, and print |
| 187 | them verbatim. Without this option, pathnames with "unusual" |
| 188 | characters are quoted as explained for the configuration |
| 189 | variable `core.quotePath` (see linkgit:git-config[1]). |
| 190 | |
| 191 | `-o`:: |
| 192 | `--only-matching`:: |
| 193 | Print only the matched (non-empty) parts of a matching line, with each such |
| 194 | part on a separate output line. |
| 195 | |
| 196 | `-c`:: |
| 197 | `--count`:: |
| 198 | Instead of showing every matched line, show the number of |
| 199 | lines that match. |
| 200 | |
| 201 | `--color[=<when>]`:: |
| 202 | Show colored matches. |
| 203 | The value must be `always` (the default), `never`, or `auto`. |
| 204 | |
| 205 | `--no-color`:: |
| 206 | Turn off match highlighting, even when the configuration file |
| 207 | gives the default to color output. |
| 208 | Same as `--color=never`. |
| 209 | |
| 210 | `--break`:: |
| 211 | Print an empty line between matches from different files. |
| 212 | |
| 213 | `--heading`:: |
| 214 | Show the filename above the matches in that file instead of |
| 215 | at the start of each shown line. |
| 216 | |
| 217 | `-p`:: |
| 218 | `--show-function`:: |
| 219 | Show the preceding line that contains the function name of |
| 220 | the match, unless the matching line is a function name itself. |
| 221 | The name is determined in the same way as `git diff` works out |
| 222 | patch hunk headers (see 'Defining a custom hunk-header' in |
| 223 | linkgit:gitattributes[5]). |
| 224 | |
| 225 | `-<num>`:: |
| 226 | `-C <num>`:: |
| 227 | `--context <num>`:: |
| 228 | Show _<num>_ leading and trailing lines, and place a line |
| 229 | containing `--` between contiguous groups of matches. |
| 230 | |
| 231 | `-A <num>`:: |
| 232 | `--after-context <num>`:: |
| 233 | Show _<num>_ trailing lines, and place a line containing |
| 234 | `--` between contiguous groups of matches. |
| 235 | |
| 236 | `-B <num>`:: |
| 237 | `--before-context <num>`:: |
| 238 | Show _<num>_ leading lines, and place a line containing |
| 239 | `--` between contiguous groups of matches. |
| 240 | |
| 241 | `-W`:: |
| 242 | `--function-context`:: |
| 243 | Show the surrounding text from the previous line containing a |
| 244 | function name up to the one before the next function name, |
| 245 | effectively showing the whole function in which the match was |
| 246 | found. The function names are determined in the same way as |
| 247 | `git diff` works out patch hunk headers (see 'Defining a |
| 248 | custom hunk-header' in linkgit:gitattributes[5]). |
| 249 | |
| 250 | `-m <num>`:: |
| 251 | `--max-count <num>`:: |
| 252 | Limit the amount of matches per file. When using the `-v` or |
| 253 | `--invert-match` option, the search stops after the specified |
| 254 | number of non-matches. A value of -1 will return unlimited |
| 255 | results (the default). A value of 0 will exit immediately with |
| 256 | a non-zero status. |
| 257 | |
| 258 | `--threads <num>`:: |
| 259 | Number of `grep` worker threads to use. See `NOTES ON THREADS` |
| 260 | and `grep.threads` in 'CONFIGURATION' for more information. |
| 261 | |
| 262 | `-f <file>`:: |
| 263 | Read patterns from _<file>_, one per line. |
| 264 | + |
| 265 | Passing the pattern via _<file>_ allows for providing a search pattern |
| 266 | containing a \0. |
| 267 | + |
| 268 | Not all pattern types support patterns containing \0. Git will error |
| 269 | out if a given pattern type can't support such a pattern. The |
| 270 | `--perl-regexp` pattern type when compiled against the PCRE v2 backend |
| 271 | has the widest support for these types of patterns. |
| 272 | + |
| 273 | In versions of Git before 2.23.0 patterns containing \0 would be |
| 274 | silently considered fixed. This was never documented, there were also |
| 275 | odd and undocumented interactions between e.g. non-ASCII patterns |
| 276 | containing \0 and `--ignore-case`. |
| 277 | + |
| 278 | In future versions we may learn to support patterns containing \0 for |
| 279 | more search backends, until then we'll die when the pattern type in |
| 280 | question doesn't support them. |
| 281 | |
| 282 | `-e`:: |
| 283 | The next parameter is the pattern. This option has to be |
| 284 | used for patterns starting with `-` and should be used in |
| 285 | scripts passing user input to grep. Multiple patterns are |
| 286 | combined by `or`. |
| 287 | |
| 288 | `--and`:: |
| 289 | `--or`:: |
| 290 | `--not`:: |
| 291 | `( ... )`:: |
| 292 | Specify how multiple patterns are combined using Boolean |
| 293 | expressions. `--or` is the default operator. `--and` has |
| 294 | higher precedence than `--or`. `-e` has to be used for all |
| 295 | patterns. |
| 296 | |
| 297 | `--all-match`:: |
| 298 | When giving multiple pattern expressions combined with `--or`, |
| 299 | this flag is specified to limit the match to files that |
| 300 | have lines to match all of them. |
| 301 | |
| 302 | `-q`:: |
| 303 | `--quiet`:: |
| 304 | Do not output matched lines; instead, exit with status 0 when |
| 305 | there is a match and with non-zero status when there isn't. |
| 306 | |
| 307 | `<tree>...`:: |
| 308 | Instead of searching tracked files in the working tree, search |
| 309 | blobs in the given trees. |
| 310 | |
| 311 | `--`:: |
| 312 | Signals the end of options; the rest of the parameters |
| 313 | are _<pathspec>_ limiters. |
| 314 | |
| 315 | `<pathspec>...`:: |
| 316 | If given, limit the search to paths matching at least one pattern. |
| 317 | Both leading paths match and `glob`(7) patterns are supported. |
| 318 | + |
| 319 | For more details about the _<pathspec>_ syntax, see the `pathspec` entry |
| 320 | in linkgit:gitglossary[7]. |
| 321 | |
| 322 | EXAMPLES |
| 323 | -------- |
| 324 | |
| 325 | `git grep 'time_t' -- '*.[ch]'`:: |
| 326 | Looks for `time_t` in all tracked .c and .h files in the working |
| 327 | directory and its subdirectories. |
| 328 | |
| 329 | `git grep -e '#define' --and \( -e MAX_PATH -e PATH_MAX \)`:: |
| 330 | Looks for a line that has `#define` and either `MAX_PATH` or |
| 331 | `PATH_MAX`. |
| 332 | |
| 333 | `git grep --all-match -e NODE -e Unexpected`:: |
| 334 | Looks for a line that has `NODE` or `Unexpected` in |
| 335 | files that have lines that match both. |
| 336 | |
| 337 | `git grep solution -- :^Documentation`:: |
| 338 | Looks for `solution`, excluding files in `Documentation`. |
| 339 | |
| 340 | NOTES ON THREADS |
| 341 | ---------------- |
| 342 | |
| 343 | The `--threads` option (and the `grep.threads` configuration) will be ignored when |
| 344 | `--open-files-in-pager` is used, forcing a single-threaded execution. |
| 345 | |
| 346 | When grepping the object store (with `--cached` or giving tree objects), running |
| 347 | with multiple threads might perform slower than single-threaded if `--textconv` |
| 348 | is given and there are too many text conversions. Thus, if low performance is |
| 349 | experienced in this case, it might be desirable to use `--threads=1`. |
| 350 | |
| 351 | CONFIGURATION |
| 352 | ------------- |
| 353 | |
| 354 | include::includes/cmd-config-section-all.adoc[] |
| 355 | |
| 356 | include::config/grep.adoc[] |
| 357 | |
| 358 | GIT |
| 359 | --- |
| 360 | Part of the linkgit:git[1] suite |