man1/git-grep.1

'\" 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: 2026-09-16
.\"    Manual: Git Manual
.\"    Source: Git 2.56.0.rc1
.\"  Language: English
.\"
.TH "GIT\-GREP" "1" "2026-09-16" "Git 2\&.56\&.0\&.rc1" "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
\fBgit\fR \fBgrep\fR [\fB\-a\fR | \fB\-\-text\fR] [\fB\-I\fR] [\fB\-\-textconv\fR] [\fB\-i\fR | \fB\-\-ignore\-case\fR] [\fB\-w\fR | \fB\-\-word\-regexp\fR]
	   [\fB\-v\fR | \fB\-\-invert\-match\fR] [\fB\-h\fR|\fB\-H\fR] [\fB\-\-full\-name\fR]
	   [\fB\-E\fR | \fB\-\-extended\-regexp\fR] [\fB\-G\fR | \fB\-\-basic\-regexp\fR]
	   [\fB\-P\fR | \fB\-\-perl\-regexp\fR]
	   [\fB\-F\fR | \fB\-\-fixed\-strings\fR] [\fB\-n\fR | \fB\-\-line\-number\fR] [\fB\-\-column\fR]
	   [\fB\-l\fR | \fB\-\-files\-with\-matches\fR] [\fB\-L\fR | \fB\-\-files\-without\-match\fR]
	   [(\fB\-O\fR | \fB\-\-open\-files\-in\-pager\fR) [\fI<pager>\fR]]
	   [\fB\-z\fR | \fB\-\-null\fR]
	   [ \fB\-o\fR | \fB\-\-only\-matching\fR ] [\fB\-c\fR | \fB\-\-count\fR] [\fB\-\-all\-match\fR] [\fB\-q\fR | \fB\-\-quiet\fR]
	   [\fB\-\-max\-depth\fR \fI<depth>\fR] [\fB\-\-\fR[\fBno\-\fR]\fBrecursive\fR]
	   [\fB\-\-color\fR[\fB=\fR\fI<when>\fR] | \fB\-\-no\-color\fR]
	   [\fB\-\-break\fR] [\fB\-\-heading\fR] [\fB\-p\fR | \fB\-\-show\-function\fR]
	   [\fB\-A\fR \fI<post\-context>\fR] [\fB\-B\fR \fI<pre\-context>\fR] [\fB\-C\fR \fI<context>\fR]
	   [\fB\-W\fR | \fB\-\-function\-context\fR]
	   [(\fB\-m\fR | \fB\-\-max\-count\fR) \fI<num>\fR]
	   [\fB\-\-threads\fR \fI<num>\fR]
	   [\fB\-f\fR \fI<file>\fR] [\fB\-e\fR] \fI<pattern>\fR
	   [\fB\-\-and\fR|\fB\-\-or\fR|\fB\-\-not\fR|(|)|\fB\-e\fR \fI<pattern>\fR\&...\:]
	   [\fB\-\-recurse\-submodules\fR] [\fB\-\-parent\-basename\fR \fI<basename>\fR]
	   [ [\fB\-\-\fR[\fBno\-\fR]\fBexclude\-standard\fR] [\fB\-\-cached\fR | \fB\-\-untracked\fR | \fB\-\-no\-index\fR] | \fI<tree>\fR\&...\:]
	   [\fB\-\-\fR] [\fI<pathspec>\fR\&...\:]
.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
\fB\-\-cached\fR
.RS 4
Instead of searching tracked files in the working tree, search blobs registered in the index file\&.
.RE
.PP
\fB\-\-untracked\fR
.RS 4
In addition to searching in the tracked files in the working tree, search also in untracked files\&.
.RE
.PP
\fB\-\-no\-index\fR
.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(1) utility with its
\fB\-r\fR
option specified, but with some additional benefits, such as using pathspec patterns to limit paths; see the
\fBpathspec\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
\fB\-\-no\-exclude\-standard\fR
.RS 4
Also search in ignored files by not honoring the \&.\fBgitignore\fR
mechanism\&. Only useful with
\fB\-\-untracked\fR\&.
.RE
.PP
\fB\-\-exclude\-standard\fR
.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
\fB\-\-recurse\-submodules\fR
.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
\fB\-a\fR, \fB\-\-text\fR
.RS 4
Process binary files as if they were text\&.
.RE
.PP
\fB\-\-textconv\fR
.RS 4
Honor textconv filter settings\&.
.RE
.PP
\fB\-\-no\-textconv\fR
.RS 4
Do not honor textconv filter settings\&. This is the default\&.
.RE
.PP
\fB\-i\fR, \fB\-\-ignore\-case\fR
.RS 4
Ignore case differences between the patterns and the files\&.
.RE
.PP
\fB\-I\fR
.RS 4
Don\(cqt match the pattern in binary files\&.
.RE
.PP
\fB\-\-max\-depth\fR \fI<depth>\fR
.RS 4
For each
\fI<pathspec>\fR
given on command line, descend at most
\fI<depth>\fR
levels of directories\&. A value of \-1 means no limit\&. This option is ignored if
\fI<pathspec>\fR
contains active wildcards\&. In other words if "a*" matches a directory named "a*", "*" is matched literally so
\fB\-\-max\-depth\fR
is still effective\&.
.RE
.PP
\fB\-r\fR, \fB\-\-recursive\fR
.RS 4
Same as
\fB\-\-max\-depth=\-1\fR; this is the default\&.
.RE
.PP
\fB\-\-no\-recursive\fR
.RS 4
Same as
\fB\-\-max\-depth=0\fR\&.
.RE
.PP
\fB\-w\fR, \fB\-\-word\-regexp\fR
.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
\fB\-v\fR, \fB\-\-invert\-match\fR
.RS 4
Select non\-matching lines\&.
.RE
.PP
\fB\-h\fR, \fB\-H\fR
.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
\fB\-\-full\-name\fR
.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
\fB\-E\fR, \fB\-\-extended\-regexp\fR, \fB\-G\fR, \fB\-\-basic\-regexp\fR
.RS 4
Use POSIX extended/basic regexp for patterns\&. Default is to use basic regexp\&.
.RE
.PP
\fB\-P\fR, \fB\-\-perl\-regexp\fR
.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
\fB\-F\fR, \fB\-\-fixed\-strings\fR
.RS 4
Use fixed strings for patterns (don\(cqt interpret pattern as a regex)\&.
.RE
.PP
\fB\-n\fR, \fB\-\-line\-number\fR
.RS 4
Prefix the line number to matching lines\&.
.RE
.PP
\fB\-\-column\fR
.RS 4
Prefix the 1\-indexed byte\-offset of the first match from the start of the matching line\&.
.RE
.PP
\fB\-l\fR, \fB\-\-files\-with\-matches\fR, \fB\-\-name\-only\fR, \fB\-L\fR, \fB\-\-files\-without\-match\fR
.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
\fBgit\fR
\fBdiff\fR,
\fB\-\-name\-only\fR
is a synonym for
\fB\-\-files\-with\-matches\fR\&.
.RE
.PP
\fB\-O\fR[\fI<pager>\fR], \fB\-\-open\-files\-in\-pager\fR[\fB=\fR\fI<pager>\fR]
.RS 4
Open the matching files in the pager (not the output of
\fBgrep\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
\fB\-z\fR, \fB\-\-null\fR
.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
\fB\-o\fR, \fB\-\-only\-matching\fR
.RS 4
Print only the matched (non\-empty) parts of a matching line, with each such part on a separate output line\&.
.RE
.PP
\fB\-c\fR, \fB\-\-count\fR
.RS 4
Instead of showing every matched line, show the number of lines that match\&.
.RE
.PP
\fB\-\-color\fR[\fB=\fR\fI<when>\fR]
.RS 4
Show colored matches\&. The value must be
\fBalways\fR
(the default),
\fBnever\fR, or
\fBauto\fR\&.
.RE
.PP
\fB\-\-no\-color\fR
.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
\fB\-\-break\fR
.RS 4
Print an empty line between matches from different files\&.
.RE
.PP
\fB\-\-heading\fR
.RS 4
Show the filename above the matches in that file instead of at the start of each shown line\&.
.RE
.PP
\fB\-p\fR, \fB\-\-show\-function\fR
.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
\fB\-\fR\fI<num>\fR, \fB\-C\fR \fI<num>\fR, \fB\-\-context\fR \fI<num>\fR
.RS 4
Show
\fI<num>\fR
leading and trailing lines, and place a line containing
\fB\-\-\fR
between contiguous groups of matches\&.
.RE
.PP
\fB\-A\fR \fI<num>\fR, \fB\-\-after\-context\fR \fI<num>\fR
.RS 4
Show
\fI<num>\fR
trailing lines, and place a line containing
\fB\-\-\fR
between contiguous groups of matches\&.
.RE
.PP
\fB\-B\fR \fI<num>\fR, \fB\-\-before\-context\fR \fI<num>\fR
.RS 4
Show
\fI<num>\fR
leading lines, and place a line containing
\fB\-\-\fR
between contiguous groups of matches\&.
.RE
.PP
\fB\-W\fR, \fB\-\-function\-context\fR
.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
\fB\-m\fR \fI<num>\fR, \fB\-\-max\-count\fR \fI<num>\fR
.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
\fB\-\-threads\fR \fI<num>\fR
.RS 4
Number of
\fBgrep\fR
worker threads to use\&. See
\fBNOTES\fR
\fBON\fR
\fBTHREADS\fR
and
\fBgrep\&.threads\fR
in
\fICONFIGURATION\fR
for more information\&.
.RE
.PP
\fB\-f\fR \fI<file>\fR
.RS 4
Read patterns from
\fI<file>\fR, one per line\&.
.sp
Passing the pattern via
\fI<file>\fR
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
\fB\-e\fR
.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
\fBor\fR\&.
.RE
.PP
\fB\-\-and\fR, \fB\-\-or\fR, \fB\-\-not\fR, ( \fB\&.\&.\&.\fR )
.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
\fB\-\-all\-match\fR
.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
\fB\-q\fR, \fB\-\-quiet\fR
.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
\fI<tree>\fR\&.\&.\&.
.RS 4
Instead of searching tracked files in the working tree, search blobs in the given trees\&.
.RE
.PP
\fB\-\-\fR
.RS 4
Signals the end of options; the rest of the parameters are
\fI<pathspec>\fR
limiters\&.
.RE
.PP
\fI<pathspec>\fR\&.\&.\&.
.RS 4
If given, limit the search to paths matching at least one pattern\&. Both leading paths match and
\fBglob\fR(7) patterns are supported\&.
.sp
For more details about the
\fI<pathspec>\fR
syntax, see the
\fBpathspec\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 \fB\e\fR( \fB\-e\fR \fBMAX_PATH\fR \fB\-e\fR \fBPATH_MAX\fR \fB\e\fR)
.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
\fBgrep\&.lineNumber\fR
.RS 4
If set to
\fBtrue\fR, enable
\fB\-n\fR
option by default\&.
.RE
.PP
\fBgrep\&.column\fR
.RS 4
If set to
\fBtrue\fR, enable the
\fB\-\-column\fR
option by default\&.
.RE
.PP
\fBgrep\&.patternType\fR
.RS 4
Set the default matching behavior\&. Using a value of
\fBbasic\fR,
\fBextended\fR,
\fBfixed\fR, or
\fBperl\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
\fBdefault\fR
will use the
\fBgrep\&.extendedRegexp\fR
option to choose between
\fBbasic\fR
and
\fBextended\fR\&.
.RE
.PP
\fBgrep\&.extendedRegexp\fR
.RS 4
If set to
\fBtrue\fR, 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
\fBdefault\fR\&.
.RE
.PP
\fBgrep\&.threads\fR
.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
\fBgrep\&.fullName\fR
.RS 4
If set to
\fBtrue\fR, enable
\fB\-\-full\-name\fR
option by default\&.
.RE
.PP
\fBgrep\&.fallbackToNoIndex\fR
.RS 4
If set to
\fBtrue\fR, 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
\fBfalse\fR\&.
.RE
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite