How to use `git grep`

Greg Foster
Greg Foster
Graphite software engineer

git grep searches for patterns in the tracked files in the Git repository. Unlike the standard Linux grep command, which operates on the file system, git grep operates on the contents tracked by Git, allowing you to search through your project's history, specific commits, or even staged files (files on your local machine that have been staged for commit to the remote repository but haven't been pushed yet). This guide will cover how to effectively use git grep, providing examples and explaining the command's available options.

To search for a string in the tracked files in your current directory and its subdirectories, you can run:

Terminal
git grep "string"

git grep is recursive by default, meaning it searches through all subdirectories of the current directory.

The git grep command is also packed with additional functionality that you can use to refine the search results it provides. Here are a few commonly used options to get you started:

  1. Show line numbers where the string appears:

    Terminal
    git grep -n "string"

    The -n option makes it easier to navigate the files in your search by providing line numbers.

  2. Search in a specific branch:

    Terminal
    git grep "string" branch-name

    This searches for "string" within all files tracked under the specified branch.

  3. Search with regular expressions:

    Terminal
    git grep -E "regex"

    Using -E allows you to input patterns as extended regular expressions.

  4. Search using specific file extensions:

    Terminal
    git grep "string" -- '*.txt'

    By adding -- '\*.FILETYPE'to the end of your grep command you can limit the search to specific file types. In the example above we're limiting our search to files ending in.txt.

  5. Show filenames only:

    Terminal
    git grep -l "string"

    The -l (lowercase L) option will list filenames where the string occurs, without showing the occurrences.

  6. Search in all files under a specific directory:

    Terminal
    git grep "string" -- directory/

    Restricts the search to a specific directory within the repository.

  7. Search for a string in the contents of staged files:

    Terminal
    git grep --cached "string"

    This option allows you to search in files that are staged (added to the index but not yet committed).

  8. Escape special characters in searches:

    Terminal
    git grep "pattern\|pattern"

    Use backslashes to escape special characters that are part of the regular expression syntax.

  • Combine conditions: You can combine multiple search conditions using logical operators:

    Terminal
    git grep -e "pattern1" --and -e "pattern2"
  • Search between commits: For searching changes between two commits, use:

    Terminal
    git diff --name-only | xargs git grep "string"

    This combination first lists files changed between commits and then greps through them.

  • Search previous commits: To search in an old version of the repository, specify the commit:

    Terminal
    git grep "string" <commit-hash>
  • Use git grep with Git Bash on Windows: git grep works out of the box in Git Bash on Windows, providing powerful search capabilities in a Unix-like command-line environment.

Imagine you have a function named calculateInterest used in a financial application. You suspect that this function might be called in multiple places, and you want to review all occurrences to ensure they correctly implement an updated interest calculation formula. In order to run this search, you can use git grep.

To find every instance where calculateInterest is used in your codebase, you would run the following command:

Terminal
git grep "calculateInterest"

This will search for the string "calculateInterest" in all files in your current branch's working directory.

If there are matches, the output will look something like this:

Terminal
src/accounting/loans.js:let annualInterest = calculateInterest(loanAmount, interestRate);
tests/loans.test.js:expected = calculateInterest(1000, 0.05); // Testing with principal and rate
docs/examples.txt:Use calculateInterest function to determine your payment.
  • Each line in the output shows:
    • The file path (src/accounting/loans.js, tests/loans.test.js, docs/examples.txt).
    • The specific line where calculateInterest appears.
  • This gives you a direct reference to where you need to review or change the implementation.

If you want to ensure that the function isn’t used in any historical commits or in other branches, you can expand your search to include every commit:

Terminal
git grep "calculateInterest" $(git rev-list --all)

This searches for the string in all commits across all branches, providing a comprehensive view of every time the function was ever added, used, or modified in the repository's history.

For further reading on git grep see the official git documentation.

Stay unblocked. Ship faster.
Experience the new developer workflow - create, review, and merge code continuously. Get started with one command.
Get started

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2