info > GIT-GREP(1)

man perldoc info pydoc3 ri search

📛 NAME

git-grep – Print lines matching a pattern

🚀 Quick Reference

Use Case	Command	Description
🔍 Search tracked files for a pattern	git grep <pattern>	Search working tree tracked files
🔤 Case‑insensitive search	git grep -i <pattern>	Ignore case when matching
🗂️ Search only file names	git grep -l <pattern>	List files that contain matches
🚫 Invert match	git grep -v <pattern>	Show lines that do NOT match
🔢 Show line numbers	git grep -n <pattern>	Prefix line numbers to output
🧮 Count matches per file	git grep -c <pattern>	Show count of matching lines
📄 Search staged (cached) content	git grep --cached <pattern>	Search blobs in the index
📜 Search specific tree (commit/tag)	git grep <pattern> <tree>	Search blobs in given tree objects
📁 Limit to file patterns	git grep <pattern> -- '*.c'	Restrict search to matching paths
🔬 Boolean combinations	git grep -e 'pattern1' --and -e 'pattern2'	Combine patterns with AND/OR/NOT

📖 SYNOPSIS

git grep [-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>...]

📝 DESCRIPTION

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.

⚙️ OPTIONS

• --cached  💾 Instead of searching tracked files in the working tree, search blobs registered in the index file.
• --no-index  📂 Search files in the current directory that is not managed by Git.
• --untracked  ➕ Also search in untracked files (in addition to tracked files).
• --no-exclude-standard  🚫 Ignore .gitignore and also search in ignored files. Only useful with --untracked.
• --exclude-standard  🚫📄 Do not pay attention to ignored files specified via .gitignore. Only useful with --no-index.
• --recurse-submodules  🔁 Recursively search in each active and checked‑out submodule. Has no effect if --no-index is given.
• -a, --text  📄 Process binary files as if they were text.
• --textconv  🎨 Honor textconv filter settings.
• --no-textconv  🚫🎨 Do not honor textconv filter settings (default).
• -i, --ignore-case  🔤 Ignore case differences between patterns and files.
• -I  🛑 Don’t match the pattern in binary files.
• --max-depth <depth>  📏 Descend at most <depth> levels of directories for each <pathspec>. A value of -1 means no limit. Ignored if <pathspec> contains active wildcards.
• -r, --recursive  🔁 Same as --max-depth=-1 (default).
• --no-recursive  🔁❌ Same as --max-depth=0.
• -w, --word-regexp  🔤 Match pattern only at word boundary (beginning/end of word).
• -v, --invert-match  🚫 Select non‑matching lines.
• -h, -H  📛 By default shows filename for each match. -h suppresses it; -H overrides an earlier -h.
• --full-name  📁 Output paths relative to project top directory instead of current subdirectory.
• -E, --extended-regexp, -G, --basic-regexp  🔍 Use POSIX extended/basic regexp. Default is basic.
• -P, --perl-regexp  🐪 Use Perl‑compatible regular expressions. Optional compile‑time dependency.
• -F, --fixed-strings  🔤 Use fixed strings (no regex interpretation).
• -n, --line-number  🔢 Prefix line number to matching lines.
• --column  📍 Prefix 1‑indexed byte‑offset of first match from start of line.
• -l, --files-with-matches, --name-only  📄 Show only file names that contain matches. -L, --files-without-match shows files that do NOT contain matches.
• -O[<pager>], --open-files-in-pager[=<pager>]  📄 Open matching files in pager (e.g., less, vi). If pager is unspecified, uses core.pager (see git-config(1)).
• -z, --null  🔪 Use \0 as pathname delimiter; unusual characters are printed verbatim (see core.quotePath in git-config(1)).
• -o, --only-matching  🎯 Print only the matched (non‑empty) parts of a line, each on a separate line.
• -c, --count  🧮 Show number of matching lines instead of each line.
• --color[=<when>]  🌈 Show colored matches. Value: always (default), never, or auto.
• --no-color  🚫🌈 Turn off match highlighting. Same as --color=never.
• --break  🔲 Print an empty line between matches from different files.
• --heading  📑 Show filename above matches instead of at start of each line.
• -p, --show-function  📐 Show preceding line containing function name of the match (same as git diff hunk headers).
• -<num>, -C <num>, --context <num>  📏 Show <num> leading and trailing lines, with -- between contiguous groups.
• -A <num>, --after-context <num>  📏 Show <num> trailing lines.
• -B <num>, --before-context <num>  📏 Show <num> leading lines.
• -W, --function-context  📐 Show surrounding text from previous function name to next, effectively showing the whole function containing the match.
• --threads <num>  🧵 Number of grep worker threads (see also grep.threads in CONFIGURATION).
• -f <file>  📄 Read patterns from file, one per line. Allows patterns containing \0 (depending on pattern type; PCRE v2 has widest support). Before Git 2.23.0 such patterns were silently treated as fixed.
• -e  🔤 The next parameter is the pattern. Must be used for patterns starting with -. Multiple -e patterns are combined with OR.
• --and, --or, --not, ( ... )  🔗 Specify Boolean combination of patterns. --or is default. --and has higher precedence than --or. Use -e for each pattern.
• --all-match  ✅ When multiple patterns are combined with --or, limit to files that have lines matching ALL of them.
• -q, --quiet  🔇 Do not output matched lines; exit with status 0 when match found, non‑zero otherwise.
• <tree>...  🌳 Search blobs in given tree objects instead of tracked files in working tree.
• --  🚧 Signals end of options; remaining parameters are <pathspec> limiters.
• <pathspec>...  📁 If given, limit search to paths matching at least one pattern. Supports leading paths match and glob(7) patterns. See pathspec entry in gitglossary(7).

💡 EXAMPLES

git grep 'time_t' -- '*.[ch]'

 🔍 Looks for time_t in all tracked .c and .h files in the working directory and its subdirectories.

git grep -e '#define' --and \( -e MAX_PATH -e PATH_MAX \)

 🔍 Looks for a line that has #define and either MAX_PATH or PATH_MAX.

git grep --all-match -e NODE -e Unexpected

 🔍 Looks for a line that has NODE or Unexpected in files that have lines that match both.

git grep solution -- :^Documentation

 🔍 Looks for solution, excluding files in Documentation.

🧵 NOTES ON THREADS

The --threads option (and grep.threads configuration) will be ignored when --open-files-in-pager is used, forcing single‑threaded execution.

When grepping the object store (with --cached or giving tree objects), running with multiple threads might perform slower than single threaded if --textconv is given and there are many text conversions. So if you experience low performance in this case, it might be desirable to use --threads=1.

🔧 CONFIGURATION

• grep.lineNumber  🔢 If set to true, enable -n option by default.
• grep.column  📍 If set to true, enable the --column option by default.
• grep.patternType  🔍 Set the default matching behavior: basic, extended, fixed, or perl enable the corresponding --*regexp/--fixed-strings option; default returns to default.
• grep.extendedRegexp  🔍 If set to true, enable --extended-regexp by default. Ignored when grep.patternType is set to a non‑default value.
• grep.threads  🧵 Number of grep worker threads. If unset or 0, Git uses as many threads as logical cores available.
• grep.fullName  📁 If set to true, enable --full-name by default.
• grep.fallbackToNoIndex  📂 If set to true, fall back to git grep --no-index if executed outside a Git repository. Defaults to false.

📚 GIT

Part of the git(1) suite. Git 2.34.1 02/26/2026

📛 NAME 🚀 Quick Reference 📖 SYNOPSIS 📝 DESCRIPTION ⚙️ OPTIONS 💡 EXAMPLES 🧵 NOTES ON THREADS 🔧 CONFIGURATION 📚 GIT