git-grep

Search for a string in tracked files

$ git grep [search_string]

$ git grep [search_string] -- [file_glob_pattern]

$ git grep --recurse-submodules [search_string]

$ git grep [search_string] [HEAD~2]

$ git grep [search_string] $(git rev-list --all)

git grep [options] (-e pattern | -f file) ... [tree-ish...] [--] [pathspec...]

-i, --ignore-case
    Ignores case differences when matching patterns.

-w, --word-regexp
    Matches only whole words; the pattern must match only a sequence of "word" characters.

-v, --invert-match
    Selects non-matching lines.

-n, --line-number
    Shows line numbers of matching lines.

-c, --count
    Suppresses normal output; instead, prints a count of matching lines for each input file.

-l, --files-with-matches
    Suppresses normal output; instead, prints the name of each input file from which output would normally have been printed.

-L, --files-without-matches
    Suppresses normal output; instead, prints the name of each input file from which no output would normally have been printed.

-p, --show-function
    Shows the function name that the matching line is part of, if applicable.

-A , --after-context=
    Prints lines of trailing context after matching lines.

-B , --before-context=
    Prints lines of leading context before matching lines.

-C , --context=
    Prints lines of context (before and after) around matching lines.

-e
    Specifies a pattern. Useful when pattern starts with '-', or to use multiple patterns.

-f
    Reads patterns from , one per line.

--and, --or, --not
    Combines multiple patterns using boolean logic (AND, OR, NOT).

-q, --quiet
    Suppresses all output. Exits with status 0 if any match is found, 1 otherwise.

--all-match
    For patterns combined with --and, requires all patterns to match in the same line.

--untracked
    Searches files in the working tree that are not tracked by Git.

--no-index
    Searches files in the working tree that are not part of a Git repository or not in the index.

--cached
    Searches files in the Git index (staging area).

--recurse-submodules
    Recurses into submodules when searching.

--no-exclude-standard
    Does not skip files matching standard ignore rules (e.g., in .gitignore).

-j , --threads=
    Number of search threads to use. Defaults to number of CPU cores.

--format=
    Specifies the output format using printf-like placeholders.


    Specifies the tree(s) to search (e.g., 'HEAD', 'v2.0', 'origin/main'). If omitted, searches the working tree and index.


    Limits the search to specific files or directories within the repository.

git-grep is a powerful and efficient utility built into Git for searching content within files tracked by Git. Unlike standard grep(1), git-grep is Git-aware, allowing it to search not only the current working directory but also the Git index, specific commits, and trees. It automatically ignores files specified in .gitignore and git-exclude files by default, which can be overridden.

It offers superior performance for large repositories due to its ability to utilize Git's object database and optimized indexing. It can search for patterns in text and binary files, providing flexible output options like showing line numbers, filenames, and context. Its primary advantage lies in its speed and its capability to search historical versions of files without needing to check them out.

By default, git-grep treats binary files specially, reporting them as matches if the pattern is found, but without displaying content. This behavior can be controlled with options like --text. When searching untracked files or files not in the index using --untracked or --no-index, git-grep might perform slower as it cannot leverage Git's optimized object database for those files.

git-grep uses POSIX Extended Regular Expressions by default. Options like --fixed-strings (or -F) can be used to treat the pattern literally, and --basic-regexp (or -G) for basic regular expressions, similar to standard grep.

The command exits with status 0 if matches are found, 1 if no matches are found, and a value greater than 1 for errors. This makes git-grep highly suitable for use in shell scripts and automated workflows.

git-grep has been a fundamental command within the Git suite since its early days, designed to offer a Git-native search capability. Its development has consistently focused on performance, allowing it to efficiently search across large codebases and historical versions of files. It leverages Git's internal data structures and object model, making it significantly faster and more powerful for Git repositories than traditional filesystem-level grep operations, especially when searching across commits or the index.

grep(1), git-log(1), git-diff(1), git-ls-files(1)