git-grep.1 (15514B)
- '\" t
- .\" Title: git-grep
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GIT\-GREP" "1" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
- .\" -----------------------------------------------------------------
- .\" * Define some portability stuff
- .\" -----------------------------------------------------------------
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .\" http://bugs.debian.org/507673
- .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .ie \n(.g .ds Aq \(aq
- .el .ds Aq '
- .\" -----------------------------------------------------------------
- .\" * set default formatting
- .\" -----------------------------------------------------------------
- .\" disable hyphenation
- .nh
- .\" disable justification (adjust text to left margin only)
- .ad l
- .\" -----------------------------------------------------------------
- .\" * MAIN CONTENT STARTS HERE *
- .\" -----------------------------------------------------------------
- .SH "NAME"
- git-grep \- Print lines matching a pattern
- .SH "SYNOPSIS"
- .sp
- .nf
- \fIgit grep\fR [\-a | \-\-text] [\-I] [\-\-textconv] [\-i | \-\-ignore\-case] [\-w | \-\-word\-regexp]
- [\-v | \-\-invert\-match] [\-h|\-H] [\-\-full\-name]
- [\-E | \-\-extended\-regexp] [\-G | \-\-basic\-regexp]
- [\-P | \-\-perl\-regexp]
- [\-F | \-\-fixed\-strings] [\-n | \-\-line\-number] [\-\-column]
- [\-l | \-\-files\-with\-matches] [\-L | \-\-files\-without\-match]
- [(\-O | \-\-open\-files\-in\-pager) [<pager>]]
- [\-z | \-\-null]
- [ \-o | \-\-only\-matching ] [\-c | \-\-count] [\-\-all\-match] [\-q | \-\-quiet]
- [\-\-max\-depth <depth>] [\-\-[no\-]recursive]
- [\-\-color[=<when>] | \-\-no\-color]
- [\-\-break] [\-\-heading] [\-p | \-\-show\-function]
- [\-A <post\-context>] [\-B <pre\-context>] [\-C <context>]
- [\-W | \-\-function\-context]
- [(\-m | \-\-max\-count) <num>]
- [\-\-threads <num>]
- [\-f <file>] [\-e] <pattern>
- [\-\-and|\-\-or|\-\-not|(|)|\-e <pattern>\&...\:]
- [\-\-recurse\-submodules] [\-\-parent\-basename <basename>]
- [ [\-\-[no\-]exclude\-standard] [\-\-cached | \-\-untracked | \-\-no\-index] | <tree>\&...\:]
- [\-\-] [<pathspec>\&...\:]
- .fi
- .SH "DESCRIPTION"
- .sp
- 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\&.
- .SH "OPTIONS"
- .PP
- \-\-cached
- .RS 4
- Instead of searching tracked files in the working tree, search blobs registered in the index file\&.
- .RE
- .PP
- \-\-untracked
- .RS 4
- In addition to searching in the tracked files in the working tree, search also in untracked files\&.
- .RE
- .PP
- \-\-no\-index
- .RS 4
- 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
- \fBgrep\fR(\fB1\fR) utility with its
- \fB\-r\fR
- option specified, but with some additional benefits, such as using pathspec patterns to limit paths; see the
- \fIpathspec\fR
- entry in
- \fBgitglossary\fR(7)
- for more information\&.
- .sp
- This option cannot be used together with
- \fB\-\-cached\fR
- or
- \fB\-\-untracked\fR\&. See also
- \fBgrep\&.fallbackToNoIndex\fR
- in
- \fICONFIGURATION\fR
- below\&.
- .RE
- .PP
- \-\-no\-exclude\-standard
- .RS 4
- Also search in ignored files by not honoring the \&.\fBgitignore\fR
- mechanism\&. Only useful with
- \fB\-\-untracked\fR\&.
- .RE
- .PP
- \-\-exclude\-standard
- .RS 4
- Do not pay attention to ignored files specified via the \&.\fBgitignore\fR
- mechanism\&. Only useful when searching files in the current directory with
- \fB\-\-no\-index\fR\&.
- .RE
- .PP
- \-\-recurse\-submodules
- .RS 4
- Recursively search in each submodule that is active and checked out in the repository\&. When used in combination with the
- \fI<tree>\fR
- option the prefix of all submodule output will be the name of the parent project\(cqs
- \fI<tree>\fR
- object\&. This option cannot be used together with
- \fB\-\-untracked\fR, and it has no effect if
- \fB\-\-no\-index\fR
- is specified\&.
- .RE
- .PP
- \-a, \-\-text
- .RS 4
- Process binary files as if they were text\&.
- .RE
- .PP
- \-\-textconv
- .RS 4
- Honor textconv filter settings\&.
- .RE
- .PP
- \-\-no\-textconv
- .RS 4
- Do not honor textconv filter settings\&. This is the default\&.
- .RE
- .PP
- \-i, \-\-ignore\-case
- .RS 4
- Ignore case differences between the patterns and the files\&.
- .RE
- .PP
- \-I
- .RS 4
- Don\(cqt match the pattern in binary files\&.
- .RE
- .PP
- \-\-max\-depth <depth>
- .RS 4
- 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\&.
- .RE
- .PP
- \-r, \-\-recursive
- .RS 4
- Same as
- \fB\-\-max\-depth=\-1\fR; this is the default\&.
- .RE
- .PP
- \-\-no\-recursive
- .RS 4
- Same as
- \fB\-\-max\-depth=0\fR\&.
- .RE
- .PP
- \-w, \-\-word\-regexp
- .RS 4
- 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)\&.
- .RE
- .PP
- \-v, \-\-invert\-match
- .RS 4
- Select non\-matching lines\&.
- .RE
- .PP
- \-h, \-H
- .RS 4
- By default, the command shows the filename for each match\&.
- \fB\-h\fR
- option is used to suppress this output\&.
- \fB\-H\fR
- is there for completeness and does not do anything except it overrides
- \fB\-h\fR
- given earlier on the command line\&.
- .RE
- .PP
- \-\-full\-name
- .RS 4
- 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\&.
- .RE
- .PP
- \-E, \-\-extended\-regexp, \-G, \-\-basic\-regexp
- .RS 4
- Use POSIX extended/basic regexp for patterns\&. Default is to use basic regexp\&.
- .RE
- .PP
- \-P, \-\-perl\-regexp
- .RS 4
- Use Perl\-compatible regular expressions for patterns\&.
- .sp
- 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\&.
- .RE
- .PP
- \-F, \-\-fixed\-strings
- .RS 4
- Use fixed strings for patterns (don\(cqt interpret pattern as a regex)\&.
- .RE
- .PP
- \-n, \-\-line\-number
- .RS 4
- Prefix the line number to matching lines\&.
- .RE
- .PP
- \-\-column
- .RS 4
- Prefix the 1\-indexed byte\-offset of the first match from the start of the matching line\&.
- .RE
- .PP
- \-l, \-\-files\-with\-matches, \-\-name\-only, \-L, \-\-files\-without\-match
- .RS 4
- Instead of showing every matched line, show only the names of files that contain (or do not contain) matches\&. For better compatibility with
- \fIgit diff\fR,
- \fB\-\-name\-only\fR
- is a synonym for
- \fB\-\-files\-with\-matches\fR\&.
- .RE
- .PP
- \-O[<pager>], \-\-open\-files\-in\-pager[=<pager>]
- .RS 4
- Open the matching files in the pager (not the output of
- \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
- \fBpager\fR
- argument is optional; if specified, it must be stuck to the option without a space\&. If
- \fBpager\fR
- is unspecified, the default pager will be used (see
- \fBcore\&.pager\fR
- in
- \fBgit-config\fR(1))\&.
- .RE
- .PP
- \-z, \-\-null
- .RS 4
- 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
- \fBcore\&.quotePath\fR
- (see
- \fBgit-config\fR(1))\&.
- .RE
- .PP
- \-o, \-\-only\-matching
- .RS 4
- Print only the matched (non\-empty) parts of a matching line, with each such part on a separate output line\&.
- .RE
- .PP
- \-c, \-\-count
- .RS 4
- Instead of showing every matched line, show the number of lines that match\&.
- .RE
- .PP
- \-\-color[=<when>]
- .RS 4
- Show colored matches\&. The value must be always (the default), never, or auto\&.
- .RE
- .PP
- \-\-no\-color
- .RS 4
- Turn off match highlighting, even when the configuration file gives the default to color output\&. Same as
- \fB\-\-color=never\fR\&.
- .RE
- .PP
- \-\-break
- .RS 4
- Print an empty line between matches from different files\&.
- .RE
- .PP
- \-\-heading
- .RS 4
- Show the filename above the matches in that file instead of at the start of each shown line\&.
- .RE
- .PP
- \-p, \-\-show\-function
- .RS 4
- 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
- \fBgit\fR
- \fBdiff\fR
- works out patch hunk headers (see
- \fIDefining a custom hunk\-header\fR
- in
- \fBgitattributes\fR(5))\&.
- .RE
- .PP
- \-<num>, \-C <num>, \-\-context <num>
- .RS 4
- Show <num> leading and trailing lines, and place a line containing
- \fB\-\-\fR
- between contiguous groups of matches\&.
- .RE
- .PP
- \-A <num>, \-\-after\-context <num>
- .RS 4
- Show <num> trailing lines, and place a line containing
- \fB\-\-\fR
- between contiguous groups of matches\&.
- .RE
- .PP
- \-B <num>, \-\-before\-context <num>
- .RS 4
- Show <num> leading lines, and place a line containing
- \fB\-\-\fR
- between contiguous groups of matches\&.
- .RE
- .PP
- \-W, \-\-function\-context
- .RS 4
- 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
- \fBgit\fR
- \fBdiff\fR
- works out patch hunk headers (see
- \fIDefining a custom hunk\-header\fR
- in
- \fBgitattributes\fR(5))\&.
- .RE
- .PP
- \-m <num>, \-\-max\-count <num>
- .RS 4
- Limit the amount of matches per file\&. When using the
- \fB\-v\fR
- or
- \fB\-\-invert\-match\fR
- 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\&.
- .RE
- .PP
- \-\-threads <num>
- .RS 4
- Number of
- \fBgrep\fR
- worker threads to use\&. See
- \fINOTES ON THREADS\fR
- and
- \fBgrep\&.threads\fR
- in
- \fICONFIGURATION\fR
- for more information\&.
- .RE
- .PP
- \-f <file>
- .RS 4
- Read patterns from <file>, one per line\&.
- .sp
- Passing the pattern via <file> allows for providing a search pattern containing a \e0\&.
- .sp
- Not all pattern types support patterns containing \e0\&. Git will error out if a given pattern type can\(cqt support such a pattern\&. The
- \fB\-\-perl\-regexp\fR
- pattern type when compiled against the PCRE v2 backend has the widest support for these types of patterns\&.
- .sp
- 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
- \fB\-\-ignore\-case\fR\&.
- .sp
- 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\&.
- .RE
- .PP
- \-e
- .RS 4
- The next parameter is the pattern\&. This option has to be used for patterns starting with
- \fB\-\fR
- and should be used in scripts passing user input to grep\&. Multiple patterns are combined by
- \fIor\fR\&.
- .RE
- .PP
- \-\-and, \-\-or, \-\-not, ( \&...\: )
- .RS 4
- Specify how multiple patterns are combined using Boolean expressions\&.
- \fB\-\-or\fR
- is the default operator\&.
- \fB\-\-and\fR
- has higher precedence than
- \fB\-\-or\fR\&.
- \fB\-e\fR
- has to be used for all patterns\&.
- .RE
- .PP
- \-\-all\-match
- .RS 4
- When giving multiple pattern expressions combined with
- \fB\-\-or\fR, this flag is specified to limit the match to files that have lines to match all of them\&.
- .RE
- .PP
- \-q, \-\-quiet
- .RS 4
- Do not output matched lines; instead, exit with status 0 when there is a match and with non\-zero status when there isn\(cqt\&.
- .RE
- .PP
- <tree>\&...\:
- .RS 4
- Instead of searching tracked files in the working tree, search blobs in the given trees\&.
- .RE
- .PP
- \-\-
- .RS 4
- Signals the end of options; the rest of the parameters are <pathspec> limiters\&.
- .RE
- .PP
- <pathspec>\&...\:
- .RS 4
- If given, limit the search to paths matching at least one pattern\&. Both leading paths match and glob(7) patterns are supported\&.
- .sp
- For more details about the <pathspec> syntax, see the
- \fIpathspec\fR
- entry in
- \fBgitglossary\fR(7)\&.
- .RE
- .SH "EXAMPLES"
- .PP
- \fBgit\fR \fBgrep\fR \*(Aqtime_t\*(Aq \fB\-\-\fR \*(Aq*\&.[\fBch\fR]\*(Aq
- .RS 4
- Looks for
- \fBtime_t\fR
- in all tracked \&.c and \&.h files in the working directory and its subdirectories\&.
- .RE
- .PP
- \fBgit\fR \fBgrep\fR \fB\-e\fR \*(Aq#define\*(Aq \fB\-\-and\fR \e( \fB\-e\fR \fBMAX_PATH\fR \fB\-e\fR \fBPATH_MAX\fR \e)
- .RS 4
- Looks for a line that has #define and either
- \fBMAX_PATH\fR
- or
- \fBPATH_MAX\fR\&.
- .RE
- .PP
- \fBgit\fR \fBgrep\fR \fB\-\-all\-match\fR \fB\-e\fR \fBNODE\fR \fB\-e\fR \fBUnexpected\fR
- .RS 4
- Looks for a line that has
- \fBNODE\fR
- or
- \fBUnexpected\fR
- in files that have lines that match both\&.
- .RE
- .PP
- \fBgit\fR \fBgrep\fR \fBsolution\fR \fB\-\-\fR \fB:^Documentation\fR
- .RS 4
- Looks for
- \fBsolution\fR, excluding files in
- \fBDocumentation\fR\&.
- .RE
- .SH "NOTES ON THREADS"
- .sp
- 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\&.
- .sp
- 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\&.
- .SH "CONFIGURATION"
- .sp
- 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:
- .PP
- grep\&.lineNumber
- .RS 4
- If set to true, enable
- \fB\-n\fR
- option by default\&.
- .RE
- .PP
- grep\&.column
- .RS 4
- If set to true, enable the
- \fB\-\-column\fR
- option by default\&.
- .RE
- .PP
- grep\&.patternType
- .RS 4
- Set the default matching behavior\&. Using a value of
- \fIbasic\fR,
- \fIextended\fR,
- \fIfixed\fR, or
- \fIperl\fR
- will enable the
- \fB\-\-basic\-regexp\fR,
- \fB\-\-extended\-regexp\fR,
- \fB\-\-fixed\-strings\fR, or
- \fB\-\-perl\-regexp\fR
- option accordingly, while the value
- \fIdefault\fR
- will use the
- \fBgrep\&.extendedRegexp\fR
- option to choose between
- \fIbasic\fR
- and
- \fIextended\fR\&.
- .RE
- .PP
- grep\&.extendedRegexp
- .RS 4
- If set to true, enable
- \fB\-\-extended\-regexp\fR
- option by default\&. This option is ignored when the
- \fBgrep\&.patternType\fR
- option is set to a value other than
- \fIdefault\fR\&.
- .RE
- .PP
- grep\&.threads
- .RS 4
- 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\&.
- .RE
- .PP
- grep\&.fullName
- .RS 4
- If set to true, enable
- \fB\-\-full\-name\fR
- option by default\&.
- .RE
- .PP
- grep\&.fallbackToNoIndex
- .RS 4
- If set to true, fall back to
- \fBgit\fR
- \fBgrep\fR
- \fB\-\-no\-index\fR
- if
- \fBgit\fR
- \fBgrep\fR
- is executed outside of a git repository\&. Defaults to false\&.
- .RE
- .SH "GIT"
- .sp
- Part of the \fBgit\fR(1) suite