| '\" t |
| .\" Title: git-grep |
| .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
| .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> |
| .\" Date: 12/09/2018 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.20.0 |
| .\" Language: English |
| .\" |
| .TH "GIT\-GREP" "1" "12/09/2018" "Git 2\&.20\&.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] |
| [\-\-threads <num>] |
| [\-f <file>] [\-e] <pattern> |
| [\-\-and|\-\-or|\-\-not|(|)|\-e <pattern>\&...] |
| [\-\-recurse\-submodules] [\-\-parent\-basename <basename>] |
| [ [\-\-[no\-]exclude\-standard] [\-\-cached | \-\-no\-index | \-\-untracked] | <tree>\&...] |
| [\-\-] [<pathspec>\&...] |
| .fi |
| .sp |
| .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 "CONFIGURATION" |
| .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 return to the default matching behavior\&. |
| .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), 8 threads are used by default (for now)\&. |
| .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 git grep \-\-no\-index if git grep is executed outside of a git repository\&. Defaults to false\&. |
| .RE |
| .SH "OPTIONS" |
| .PP |
| \-\-cached |
| .RS 4 |
| Instead of searching tracked files in the working tree, search blobs registered in the index file\&. |
| .RE |
| .PP |
| \-\-no\-index |
| .RS 4 |
| Search files in the current directory that is not managed by Git\&. |
| .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\-exclude\-standard |
| .RS 4 |
| Also search in ignored files by not honoring the |
| \fB\&.gitignore\fR |
| mechanism\&. Only useful with |
| \fB\-\-untracked\fR\&. |
| .RE |
| .PP |
| \-\-exclude\-standard |
| .RS 4 |
| Do not pay attention to ignored files specified via the |
| \fB\&.gitignore\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 has been initialized and checked out in the repository\&. When used in combination with the <tree> option the prefix of all submodule output will be the name of the parent project\(cqs <tree> object\&. |
| .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 |
| Output \e0 instead of the character that normally follows a file name\&. |
| .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 |
| \fIgit diff\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\&. |
| .RE |
| .PP |
| \-\-threads <num> |
| .RS 4 |
| Number of grep worker threads to use\&. See |
| \fBgrep\&.threads\fR |
| in |
| \fICONFIGURATION\fR |
| for more information\&. |
| .RE |
| .PP |
| \-f <file> |
| .RS 4 |
| Read patterns from <file>, one per line\&. |
| .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 grep \(aqtime_t\(aq \-\- \(aq*\&.[ch]\(aq\fR |
| .RS 4 |
| Looks for |
| \fBtime_t\fR |
| in all tracked \&.c and \&.h files in the working directory and its subdirectories\&. |
| .RE |
| .PP |
| \fBgit grep \-e \(aq#define\(aq \-\-and \e( \-e MAX_PATH \-e PATH_MAX \e)\fR |
| .RS 4 |
| Looks for a line that has |
| \fB#define\fR |
| and either |
| \fBMAX_PATH\fR |
| or |
| \fBPATH_MAX\fR\&. |
| .RE |
| .PP |
| \fBgit grep \-\-all\-match \-e NODE \-e Unexpected\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 grep solution \-\- :^Documentation\fR |
| .RS 4 |
| Looks for |
| \fBsolution\fR, excluding files in |
| \fBDocumentation\fR\&. |
| .RE |
| .SH "GIT" |
| .sp |
| Part of the \fBgit\fR(1) suite |