man1/git-grep.1

   1 '\" t
   2 .\"     Title: git-grep
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2024-06-06
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.45.2.436.gcd77e87115
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-GREP" "1" "2024\-06\-06" "Git 2\&.45\&.2\&.436\&.gcd77e8" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-grep \- Print lines matching a pattern
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit grep\fR [\-a | \-\-text] [\-I] [\-\-textconv] [\-i | \-\-ignore\-case] [\-w | \-\-word\-regexp]
  36            [\-v | \-\-invert\-match] [\-h|\-H] [\-\-full\-name]
  37            [\-E | \-\-extended\-regexp] [\-G | \-\-basic\-regexp]
  38            [\-P | \-\-perl\-regexp]
  39            [\-F | \-\-fixed\-strings] [\-n | \-\-line\-number] [\-\-column]
  40            [\-l | \-\-files\-with\-matches] [\-L | \-\-files\-without\-match]
  41            [(\-O | \-\-open\-files\-in\-pager) [<pager>]]
  42            [\-z | \-\-null]
  43            [ \-o | \-\-only\-matching ] [\-c | \-\-count] [\-\-all\-match] [\-q | \-\-quiet]
  44            [\-\-max\-depth <depth>] [\-\-[no\-]recursive]
  45            [\-\-color[=<when>] | \-\-no\-color]
  46            [\-\-break] [\-\-heading] [\-p | \-\-show\-function]
  47            [\-A <post\-context>] [\-B <pre\-context>] [\-C <context>]
  48            [\-W | \-\-function\-context]
  49            [(\-m | \-\-max\-count) <num>]
  50            [\-\-threads <num>]
  51            [\-f <file>] [\-e] <pattern>
  52            [\-\-and|\-\-or|\-\-not|(|)|\-e <pattern>\&...]
  53            [\-\-recurse\-submodules] [\-\-parent\-basename <basename>]
  54            [ [\-\-[no\-]exclude\-standard] [\-\-cached | \-\-untracked | \-\-no\-index] | <tree>\&...]
  55            [\-\-] [<pathspec>\&...]
  56 .fi
  57 .sp
  58 .SH "DESCRIPTION"
  59 .sp
  60 Look for specified patterns in the tracked files in the work tree, blobs registered in the index file, or blobs in given tree objects\&. Patterns are lists of one or more search expressions separated by newline characters\&. An empty string as search expression matches all lines\&.
  61 .SH "OPTIONS"
  62 .PP
  63 \-\-cached
  64 .RS 4
  65 Instead of searching tracked files in the working tree, search blobs registered in the index file\&.
  66 .RE
  67 .PP
  68 \-\-untracked
  69 .RS 4
  70 In addition to searching in the tracked files in the working tree, search also in untracked files\&.
  71 .RE
  72 .PP
  73 \-\-no\-index
  74 .RS 4
  75 Search files in the current directory that is not managed by Git, or by ignoring that the current directory is managed by Git\&. This is rather similar to running the regular
  76 \fBgrep(1)\fR
  77 utility with its
  78 \fB\-r\fR
  79 option specified, but with some additional benefits, such as using pathspec patterns to limit paths; see the
  80 \fIpathspec\fR
  81 entry in
  82 \fBgitglossary\fR(7)
  83 for more information\&.
  84 .sp
  85 This option cannot be used together with
  86 \fB\-\-cached\fR
  87 or
  88 \fB\-\-untracked\fR\&. See also
  89 \fBgrep\&.fallbackToNoIndex\fR
  90 in
  91 \fICONFIGURATION\fR
  92 below\&.
  93 .RE
  94 .PP
  95 \-\-no\-exclude\-standard
  96 .RS 4
  97 Also search in ignored files by not honoring the
  98 \fB\&.gitignore\fR
  99 mechanism\&. Only useful with
 100 \fB\-\-untracked\fR\&.
 101 .RE
 102 .PP
 103 \-\-exclude\-standard
 104 .RS 4
 105 Do not pay attention to ignored files specified via the
 106 \fB\&.gitignore\fR
 107 mechanism\&. Only useful when searching files in the current directory with
 108 \fB\-\-no\-index\fR\&.
 109 .RE
 110 .PP
 111 \-\-recurse\-submodules
 112 .RS 4
 113 Recursively search in each submodule that is active and checked out in the repository\&. When used in combination with the
 114 \fI<tree>\fR
 115 option the prefix of all submodule output will be the name of the parent project\(cqs
 116 \fI<tree>\fR
 117 object\&. This option cannot be used together with
 118 \fB\-\-untracked\fR, and it has no effect if
 119 \fB\-\-no\-index\fR
 120 is specified\&.
 121 .RE
 122 .PP
 123 \-a, \-\-text
 124 .RS 4
 125 Process binary files as if they were text\&.
 126 .RE
 127 .PP
 128 \-\-textconv
 129 .RS 4
 130 Honor textconv filter settings\&.
 131 .RE
 132 .PP
 133 \-\-no\-textconv
 134 .RS 4
 135 Do not honor textconv filter settings\&. This is the default\&.
 136 .RE
 137 .PP
 138 \-i, \-\-ignore\-case
 139 .RS 4
 140 Ignore case differences between the patterns and the files\&.
 141 .RE
 142 .PP
 143 \-I
 144 .RS 4
 145 Don\(cqt match the pattern in binary files\&.
 146 .RE
 147 .PP
 148 \-\-max\-depth <depth>
 149 .RS 4
 150 For each <pathspec> given on command line, descend at most <depth> levels of directories\&. A value of \-1 means no limit\&. This option is ignored if <pathspec> contains active wildcards\&. In other words if "a*" matches a directory named "a*", "*" is matched literally so \-\-max\-depth is still effective\&.
 151 .RE
 152 .PP
 153 \-r, \-\-recursive
 154 .RS 4
 155 Same as
 156 \fB\-\-max\-depth=\-1\fR; this is the default\&.
 157 .RE
 158 .PP
 159 \-\-no\-recursive
 160 .RS 4
 161 Same as
 162 \fB\-\-max\-depth=0\fR\&.
 163 .RE
 164 .PP
 165 \-w, \-\-word\-regexp
 166 .RS 4
 167 Match the pattern only at word boundary (either begin at the beginning of a line, or preceded by a non\-word character; end at the end of a line or followed by a non\-word character)\&.
 168 .RE
 169 .PP
 170 \-v, \-\-invert\-match
 171 .RS 4
 172 Select non\-matching lines\&.
 173 .RE
 174 .PP
 175 \-h, \-H
 176 .RS 4
 177 By default, the command shows the filename for each match\&.
 178 \fB\-h\fR
 179 option is used to suppress this output\&.
 180 \fB\-H\fR
 181 is there for completeness and does not do anything except it overrides
 182 \fB\-h\fR
 183 given earlier on the command line\&.
 184 .RE
 185 .PP
 186 \-\-full\-name
 187 .RS 4
 188 When run from a subdirectory, the command usually outputs paths relative to the current directory\&. This option forces paths to be output relative to the project top directory\&.
 189 .RE
 190 .PP
 191 \-E, \-\-extended\-regexp, \-G, \-\-basic\-regexp
 192 .RS 4
 193 Use POSIX extended/basic regexp for patterns\&. Default is to use basic regexp\&.
 194 .RE
 195 .PP
 196 \-P, \-\-perl\-regexp
 197 .RS 4
 198 Use Perl\-compatible regular expressions for patterns\&.
 199 .sp
 200 Support for these types of regular expressions is an optional compile\-time dependency\&. If Git wasn\(cqt compiled with support for them providing this option will cause it to die\&.
 201 .RE
 202 .PP
 203 \-F, \-\-fixed\-strings
 204 .RS 4
 205 Use fixed strings for patterns (don\(cqt interpret pattern as a regex)\&.
 206 .RE
 207 .PP
 208 \-n, \-\-line\-number
 209 .RS 4
 210 Prefix the line number to matching lines\&.
 211 .RE
 212 .PP
 213 \-\-column
 214 .RS 4
 215 Prefix the 1\-indexed byte\-offset of the first match from the start of the matching line\&.
 216 .RE
 217 .PP
 218 \-l, \-\-files\-with\-matches, \-\-name\-only, \-L, \-\-files\-without\-match
 219 .RS 4
 220 Instead of showing every matched line, show only the names of files that contain (or do not contain) matches\&. For better compatibility with
 221 \fIgit diff\fR,
 222 \fB\-\-name\-only\fR
 223 is a synonym for
 224 \fB\-\-files\-with\-matches\fR\&.
 225 .RE
 226 .PP
 227 \-O[<pager>], \-\-open\-files\-in\-pager[=<pager>]
 228 .RS 4
 229 Open the matching files in the pager (not the output of
 230 \fIgrep\fR)\&. If the pager happens to be "less" or "vi", and the user specified only one pattern, the first file is positioned at the first match automatically\&. The
 231 \fBpager\fR
 232 argument is optional; if specified, it must be stuck to the option without a space\&. If
 233 \fBpager\fR
 234 is unspecified, the default pager will be used (see
 235 \fBcore\&.pager\fR
 236 in
 237 \fBgit-config\fR(1))\&.
 238 .RE
 239 .PP
 240 \-z, \-\-null
 241 .RS 4
 242 Use \e0 as the delimiter for pathnames in the output, and print them verbatim\&. Without this option, pathnames with "unusual" characters are quoted as explained for the configuration variable
 243 \fBcore\&.quotePath\fR
 244 (see
 245 \fBgit-config\fR(1))\&.
 246 .RE
 247 .PP
 248 \-o, \-\-only\-matching
 249 .RS 4
 250 Print only the matched (non\-empty) parts of a matching line, with each such part on a separate output line\&.
 251 .RE
 252 .PP
 253 \-c, \-\-count
 254 .RS 4
 255 Instead of showing every matched line, show the number of lines that match\&.
 256 .RE
 257 .PP
 258 \-\-color[=<when>]
 259 .RS 4
 260 Show colored matches\&. The value must be always (the default), never, or auto\&.
 261 .RE
 262 .PP
 263 \-\-no\-color
 264 .RS 4
 265 Turn off match highlighting, even when the configuration file gives the default to color output\&. Same as
 266 \fB\-\-color=never\fR\&.
 267 .RE
 268 .PP
 269 \-\-break
 270 .RS 4
 271 Print an empty line between matches from different files\&.
 272 .RE
 273 .PP
 274 \-\-heading
 275 .RS 4
 276 Show the filename above the matches in that file instead of at the start of each shown line\&.
 277 .RE
 278 .PP
 279 \-p, \-\-show\-function
 280 .RS 4
 281 Show the preceding line that contains the function name of the match, unless the matching line is a function name itself\&. The name is determined in the same way as
 282 \fBgit diff\fR
 283 works out patch hunk headers (see
 284 \fIDefining a custom hunk\-header\fR
 285 in
 286 \fBgitattributes\fR(5))\&.
 287 .RE
 288 .PP
 289 \-<num>, \-C <num>, \-\-context <num>
 290 .RS 4
 291 Show <num> leading and trailing lines, and place a line containing
 292 \fB\-\-\fR
 293 between contiguous groups of matches\&.
 294 .RE
 295 .PP
 296 \-A <num>, \-\-after\-context <num>
 297 .RS 4
 298 Show <num> trailing lines, and place a line containing
 299 \fB\-\-\fR
 300 between contiguous groups of matches\&.
 301 .RE
 302 .PP
 303 \-B <num>, \-\-before\-context <num>
 304 .RS 4
 305 Show <num> leading lines, and place a line containing
 306 \fB\-\-\fR
 307 between contiguous groups of matches\&.
 308 .RE
 309 .PP
 310 \-W, \-\-function\-context
 311 .RS 4
 312 Show the surrounding text from the previous line containing a function name up to the one before the next function name, effectively showing the whole function in which the match was found\&. The function names are determined in the same way as
 313 \fBgit diff\fR
 314 works out patch hunk headers (see
 315 \fIDefining a custom hunk\-header\fR
 316 in
 317 \fBgitattributes\fR(5))\&.
 318 .RE
 319 .PP
 320 \-m <num>, \-\-max\-count <num>
 321 .RS 4
 322 Limit the amount of matches per file\&. When using the
 323 \fB\-v\fR
 324 or
 325 \fB\-\-invert\-match\fR
 326 option, the search stops after the specified number of non\-matches\&. A value of \-1 will return unlimited results (the default)\&. A value of 0 will exit immediately with a non\-zero status\&.
 327 .RE
 328 .PP
 329 \-\-threads <num>
 330 .RS 4
 331 Number of
 332 \fBgrep\fR
 333 worker threads to use\&. See
 334 \fINOTES ON THREADS\fR
 335 and
 336 \fBgrep\&.threads\fR
 337 in
 338 \fICONFIGURATION\fR
 339 for more information\&.
 340 .RE
 341 .PP
 342 \-f <file>
 343 .RS 4
 344 Read patterns from <file>, one per line\&.
 345 .sp
 346 Passing the pattern via <file> allows for providing a search pattern containing a \e0\&.
 347 .sp
 348 Not all pattern types support patterns containing \e0\&. Git will error out if a given pattern type can\(cqt support such a pattern\&. The
 349 \fB\-\-perl\-regexp\fR
 350 pattern type when compiled against the PCRE v2 backend has the widest support for these types of patterns\&.
 351 .sp
 352 In versions of Git before 2\&.23\&.0 patterns containing \e0 would be silently considered fixed\&. This was never documented, there were also odd and undocumented interactions between e\&.g\&. non\-ASCII patterns containing \e0 and
 353 \fB\-\-ignore\-case\fR\&.
 354 .sp
 355 In future versions we may learn to support patterns containing \e0 for more search backends, until then we\(cqll die when the pattern type in question doesn\(cqt support them\&.
 356 .RE
 357 .PP
 358 \-e
 359 .RS 4
 360 The next parameter is the pattern\&. This option has to be used for patterns starting with
 361 \fB\-\fR
 362 and should be used in scripts passing user input to grep\&. Multiple patterns are combined by
 363 \fIor\fR\&.
 364 .RE
 365 .PP
 366 \-\-and, \-\-or, \-\-not, ( \&... )
 367 .RS 4
 368 Specify how multiple patterns are combined using Boolean expressions\&.
 369 \fB\-\-or\fR
 370 is the default operator\&.
 371 \fB\-\-and\fR
 372 has higher precedence than
 373 \fB\-\-or\fR\&.
 374 \fB\-e\fR
 375 has to be used for all patterns\&.
 376 .RE
 377 .PP
 378 \-\-all\-match
 379 .RS 4
 380 When giving multiple pattern expressions combined with
 381 \fB\-\-or\fR, this flag is specified to limit the match to files that have lines to match all of them\&.
 382 .RE
 383 .PP
 384 \-q, \-\-quiet
 385 .RS 4
 386 Do not output matched lines; instead, exit with status 0 when there is a match and with non\-zero status when there isn\(cqt\&.
 387 .RE
 388 .PP
 389 <tree>\&...
 390 .RS 4
 391 Instead of searching tracked files in the working tree, search blobs in the given trees\&.
 392 .RE
 393 .PP
 394 \-\-
 395 .RS 4
 396 Signals the end of options; the rest of the parameters are <pathspec> limiters\&.
 397 .RE
 398 .PP
 399 <pathspec>\&...
 400 .RS 4
 401 If given, limit the search to paths matching at least one pattern\&. Both leading paths match and glob(7) patterns are supported\&.
 402 .sp
 403 For more details about the <pathspec> syntax, see the
 404 \fIpathspec\fR
 405 entry in
 406 \fBgitglossary\fR(7)\&.
 407 .RE
 408 .SH "EXAMPLES"
 409 .PP
 410 \fBgit grep \*(Aqtime_t\*(Aq \-\- \*(Aq*\&.[ch]\*(Aq\fR
 411 .RS 4
 412 Looks for
 413 \fBtime_t\fR
 414 in all tracked \&.c and \&.h files in the working directory and its subdirectories\&.
 415 .RE
 416 .PP
 417 \fBgit grep \-e \*(Aq#define\*(Aq \-\-and \e( \-e MAX_PATH \-e PATH_MAX \e)\fR
 418 .RS 4
 419 Looks for a line that has
 420 \fB#define\fR
 421 and either
 422 \fBMAX_PATH\fR
 423 or
 424 \fBPATH_MAX\fR\&.
 425 .RE
 426 .PP
 427 \fBgit grep \-\-all\-match \-e NODE \-e Unexpected\fR
 428 .RS 4
 429 Looks for a line that has
 430 \fBNODE\fR
 431 or
 432 \fBUnexpected\fR
 433 in files that have lines that match both\&.
 434 .RE
 435 .PP
 436 \fBgit grep solution \-\- :^Documentation\fR
 437 .RS 4
 438 Looks for
 439 \fBsolution\fR, excluding files in
 440 \fBDocumentation\fR\&.
 441 .RE
 442 .SH "NOTES ON THREADS"
 443 .sp
 444 The \fB\-\-threads\fR option (and the \fBgrep\&.threads\fR configuration) will be ignored when \fB\-\-open\-files\-in\-pager\fR is used, forcing a single\-threaded execution\&.
 445 .sp
 446 When grepping the object store (with \fB\-\-cached\fR or giving tree objects), running with multiple threads might perform slower than single\-threaded if \fB\-\-textconv\fR is given and there are too many text conversions\&. Thus, if low performance is experienced in this case, it might be desirable to use \fB\-\-threads=1\fR\&.
 447 .SH "CONFIGURATION"
 448 .sp
 449 Everything below this line in this section is selectively included from the \fBgit-config\fR(1) documentation\&. The content is the same as what\(cqs found there:
 450 .PP
 451 grep\&.lineNumber
 452 .RS 4
 453 If set to true, enable
 454 \fB\-n\fR
 455 option by default\&.
 456 .RE
 457 .PP
 458 grep\&.column
 459 .RS 4
 460 If set to true, enable the
 461 \fB\-\-column\fR
 462 option by default\&.
 463 .RE
 464 .PP
 465 grep\&.patternType
 466 .RS 4
 467 Set the default matching behavior\&. Using a value of
 468 \fIbasic\fR,
 469 \fIextended\fR,
 470 \fIfixed\fR, or
 471 \fIperl\fR
 472 will enable the
 473 \fB\-\-basic\-regexp\fR,
 474 \fB\-\-extended\-regexp\fR,
 475 \fB\-\-fixed\-strings\fR, or
 476 \fB\-\-perl\-regexp\fR
 477 option accordingly, while the value
 478 \fIdefault\fR
 479 will use the
 480 \fBgrep\&.extendedRegexp\fR
 481 option to choose between
 482 \fIbasic\fR
 483 and
 484 \fIextended\fR\&.
 485 .RE
 486 .PP
 487 grep\&.extendedRegexp
 488 .RS 4
 489 If set to true, enable
 490 \fB\-\-extended\-regexp\fR
 491 option by default\&. This option is ignored when the
 492 \fBgrep\&.patternType\fR
 493 option is set to a value other than
 494 \fIdefault\fR\&.
 495 .RE
 496 .PP
 497 grep\&.threads
 498 .RS 4
 499 Number of grep worker threads to use\&. If unset (or set to 0), Git will use as many threads as the number of logical cores available\&.
 500 .RE
 501 .PP
 502 grep\&.fullName
 503 .RS 4
 504 If set to true, enable
 505 \fB\-\-full\-name\fR
 506 option by default\&.
 507 .RE
 508 .PP
 509 grep\&.fallbackToNoIndex
 510 .RS 4
 511 If set to true, fall back to
 512 \fBgit grep \-\-no\-index\fR
 513 if
 514 \fBgit grep\fR
 515 is executed outside of a git repository\&. Defaults to false\&.
 516 .RE
 517 .SH "GIT"
 518 .sp
 519 Part of the \fBgit\fR(1) suite