grep Git Command Guide

The git grep command searches for specified patterns in the tracked files in the work tree, blobs registered in the index file, or blobs in given tree objects. It prints lines matching the pattern allowing efficient text searching across repository history.

git grep Syntax:

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]
         [(-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>...]

Options:

Option	Description
-a, --text	Treat binary files as text
-i, --ignore-case	Case-insensitive search
-w, --word-regexp	Match whole words only
-v, --invert-match	Show non-matching lines
-G, --basic-regexp	Use basic regex (default)
-E, --extended-regexp	Use extended regex
-P, --perl-regexp	Use Perl regex
-F, --fixed-strings	Treat pattern as literal string
-n, --line-number	Show line numbers
-l, --files-with-matches	Only show filenames
-L, --files-without-match	Only show filenames without matches
-c, --count	Show count of matching lines
-o, --only-matching	Show only matched part
--cached	Search in index instead of worktree
--no-index	Search files not under Git control
-p, --show-function	Show function context

Parameters:

Parameter	Description
<pattern>	Pattern to search for
<tree>...	Tree objects to search in
<pathspec>...	Limit search to path patterns

Caution

git grep searches blobs, meaning untracked files in —no-index mode won’t be searched unless specified. Use —textconv for binary files.

git grep Command Samples:

Basic pattern search

git grep "TODO"

Searches for “TODO” in all tracked files.

Case-insensitive search

git grep -i "error"

Finds “error”, “Error”, “ERROR”, etc.

Whole word match

git grep -w "class"

Matches “class” but not “classes” or “classifier”.

Search in specific files

git grep "function" -- "*.js"

Finds “function” only in JavaScript files.

Show line numbers

git grep -n "FIXME"

Displays line numbers with matches.

Count matches per file

git grep -c "console.log"

Shows how many times each file contains “console.log”.

Search in index (staged changes)

git grep --cached "password"

Searches staged files instead of working directory.

Search in file globs

git grep "import" -- "*.py" "*.java"

Searches Python and Java files only.

Invert match (show non-matching lines)

git grep -v "DEBUG" -- "*.log"

Shows log lines that don’t contain “DEBUG”.

Files without matches

git grep -L "deprecated" -- "*.cpp"

Lists C++ files that don’t contain “deprecated”.

Only matching files

git grep -l "LICENSE" -- "*.md"

Lists markdown files containing “LICENSE”.

Show function context

git grep -p "malloc"

Shows function names where “malloc” is found.

Search specific commit

git grep "bug" HEAD~10..HEAD

Searches commits in range for “bug”.

Multiple patterns (AND)

git grep --all-match -e "error" -e "warning"

Finds lines containing both “error” and “warning”.

Fixed string search

git grep -F "$.ajax"

Treats “$.ajax” as literal text, not regex.

Show function context around matches

git grep -p func -- "*.c"

Shows function definitions containing “func” in C files.

Search across line boundaries with context

git grep -A2 -B1 "struct" -- "*.h"

Shows 1 line before and 2 lines after “struct” matches.

Tip

Use git grep for faster-than-grep searches in large repos. Combine with —cached to search staged versions. Use —textconv to search inside binary files with text filters.

How does git grep search in commits?

Specify commit ranges like git grep "pattern" HEAD~5..HEAD to search through commits. This examines the blob contents at each specified commit.

What’s the difference between git grep and regular grep?

git grep searches Git objects (blobs) in the repository history, while regular grep searches files in the current filesystem. git grep can search index, working tree, or historical versions.

Can git grep handle binary files?

By default, git grep skips binary files but --text treats them as text. Use --textconv to apply git’s text conversion filters for certain binary file types.

How do I search across file renames?

git grep searches content by examining blobs, not filenames, so it will find matches across file renames as long as the content exists in repository history.

Why is git grep fast on large repositories?

git grep operates on packed Git objects, avoiding filesystem traversal. It can use multi-threading and works directly with compressed repository data.

How do multiple pattern searches work?

Use -e pattern multiple times with --and, --or, --not to combine patterns. Parentheses (, ) create grouping for complex boolean searches.

Can I limit search depth in directory trees?

--max-depth <depth> limits how deep into directory structures git grep searches, useful for large shallow directory structures.

How do I search untracked files?

Use --no-index to search files not under Git version control: git grep --no-index "pattern" /path/to/files.

What’s the difference between —cached and —no-index?

--cached searches Git index (staged files), --no-index searches files completely outside Git repository (like regular grep).

Can git grep use PCRE (Perl Compatible Regular Expressions)?

Yes, with -P or --perl-regexp option for advanced regex features like lookbehind/behind, atomic groups, and recursive patterns.

How do I colorize output?

Use --color=always or configure color.grep in git config. Colors highlight matches in terminal output.

Can git grep search in submodules?

Use --recurse-submodules to search in Git submodules in addition to main repository.

What’s the threads option for?

--threads <num> enables multi-threaded searching for better performance on large repositories or when searching many files.

How do I make git grep case-sensitive?

By default git grep is case-sensitive. Use -i or --ignore-case for case-insensitive search.

Can I grep for entire file contents?

Use -c for counts, -l for filenames, or -L for filenames without matches. For full file content matching, combine with other tools.

How do I search for empty lines or special characters?

Use patterns like ^$ for empty lines, \t for tabs, or \\[0-9]+ for numbers. Escape special regex characters appropriately.

What’s the difference between —heading and —break?

--heading groups matches by file with filename headers, --break adds extra blank lines between file groups for better visual separation.

Applications of the git grep command

1. Code Analysis: Locate function definitions, variable usages, or API calls across codebase
2. Bug Hunting: Search for specific error messages or problematic code patterns
3. Code Reviews: Find where certain patterns or practices are used before changes
4. Refactoring: Identify all locations using deprecated functions or variables
5. Security Audits: Search for hardcoded passwords, API keys, or sensitive data
6. Consistency Checks: Ensure coding standards compliance across large repositories