Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Inspecting History

git grep command

Reference for git grep: search tracked files, any commit or the index with regular expressions, boolean patterns, context, function names, and paths, much faster than grep -r.

git grep searches the text of files that Git knows about. By default it looks at tracked files in the working tree, skips everything ignored or untracked, and never touches the .git directory. That alone makes it a better grep -r in a repository: no build output, no node_modules, no binary noise.

It can also search other states of the project: the index (--cached), a commit or tag (git grep pattern v1.0), or several revisions at once. Because it reads from Git's own data and runs in parallel threads, it stays fast on large repositories, and it understands boolean combinations of patterns (--and, --or, --not) that plain grep cannot express.

Terminal
git grep [<options>] <pattern> [<revision>...] [-- <path>...]

Try it

Bash Searching the working tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash History, boolean patterns and context

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git grep [-a] [-i] [-I] [-w] [-v] [-h | -H] [--full-name]
         [-E | -F | -P] [-n] [--column] [-l | -L] [-c] [-o] [-q]
         [-p | -W] [-A <n>] [-B <n>] [-C <n>]
         [--cached | --no-index | --untracked] [--max-depth <n>]
         [(-e <pattern>) [(--and|--or|--not|(|)|-e <pattern>)...]]
         [<tree>...] [--] [<pathspec>...]
Option Description
-n, --line-number Show line numbers.
--column Show the column of the first match.
-i Ignore case.
-w Match whole words only.
-v Select lines that do not match.
-E, -F, -P Extended regex, fixed string, Perl regex (when Git is built with PCRE). The default is basic regex.
-l, -L List only names of files with, or without, a match.
-c Print the number of matching lines per file.
-o Print only the matching part of each line.
-q Print nothing; exit 0 if something matched.
-A, -B, -C <n> Lines of context after, before, around.
-p, --show-function Show the preceding function-like line (as a header).
-W, --function-context Show the whole function around each match.
-h, -H Omit or include the file name prefix.
--full-name Print paths from the repository root even when run in a subdirectory.
--heading, --break Group matches by file, with a blank line between files.
--cached Search the index instead of the working tree.
--untracked Also search untracked, non-ignored files. --no-exclude-standard includes ignored files too.
--no-index Search files in the current directory without Git tracking (like grep -r, with Git's niceties).
--max-depth <n> Descend at most n directory levels.
-e <pattern> Give a pattern; combine with --and, --or, --not and parentheses.
--all-match With several -e patterns joined by --or, require all of them somewhere in the file.
--threads <n> Number of worker threads.
<tree>... Search these revisions instead of the working tree.
-- <pathspec>... Limit the search to paths (see Pathspec).

Returns: exit status 0 when at least one line matched, 1 when nothing matched, and a higher status on errors.

Usage notes

  • Options come before patterns and paths. git grep TODO -i fails; write git grep -i TODO. Put -- before paths that could be mistaken for revisions.
  • Revision output is prefixed as <rev>:<path>:<line>, so you can search several tags at once and see where each hit came from.
  • --and works per line, --all-match per file. -e a --and -e b needs both on one line; --all-match needs both anywhere in the same file.
  • Tracked only by default, so a file you have not added yet is not searched; use --untracked or --no-index.
  • Binary files are searched but only reported as "Binary file matches"; use -I to skip them or -a to treat them as text.
  • Regex dialect follows grep.patternType (basic, extended, fixed, perl); grep.lineNumber and grep.column set defaults.
  • Searching history for when a string appeared is a job for git log -S, not git grep.
  • Submodules are skipped unless you pass --recurse-submodules.