Skip to content
Velloreth
Developer Tools 7 min read

grep and find: A Practical Guide

Search file contents with grep and the filesystem with find. Learn the flags that matter and how to combine them safely.

By

grep: searching contents

The basic form is grep pattern file.

grep "TODO" src/main.js

Recursive searches a directory tree.

grep -r "TODO" src/

The flags that matter:

FlagMeaning
-icase-insensitive
-nshow the line number
-rrecursive
-llist only the file names
-ccount the matches
-vinvert, show the non-matching lines
-wmatch a whole word
-Ftreat the pattern as a fixed string
-Eextended regular expressions
-A nshow n lines after a match
-B nshow n lines before a match
-C nshow n lines of context

-l is often what you want. A search for a symbol usually ends with “which files use this”, not “show me every line”.

grep -rl "deprecatedFunction" src/

Context is what makes a match readable.

grep -rn -C 3 "throw new Error" src/

Limiting a grep

A recursive grep on a project directory searches node_modules and .git, which is slow and noisy.

grep -r "TODO" . \
  --exclude-dir=node_modules \
  --exclude-dir=.git \
  --exclude-dir=dist \
  --include="*.ts" \
  --include="*.tsx"

--include limits the file types, and --exclude-dir skips a directory. Both are faster than searching and filtering.

-I skips binary files, which avoids a screen of binary output.

grep -rI "config" /etc

-m stops after a number of matches per file, which is useful for a quick check.

grep -rm 1 "version" package.json

Regular expressions

Basic treats +, ?, |, ( and ) as literals.

grep "a+b" file      # matches the literal a+b

Extended treats them as operators.

grep -E "a+b" file   # matches one or more a
grep -E "^(foo|bar)" file

-F is the fixed-string mode, which is faster and avoids escaping.

grep -F "a+b" file

A pattern that starts with a dash needs -- to end the options.

grep -- "-v" file

find: searching the filesystem

The basic form is find path criteria action.

find . -name "*.log"
find /var -type f -size +100M
find . -type d -name node_modules

The criteria that matter:

CriterionMeaning
-namematch the file name (case-sensitive)
-inamematch the file name (case-insensitive)
-type fa regular file
-type da directory
-size +10Mlarger than 10 MB
-mtime -7modified in the last 7 days
-mmin -60modified in the last 60 minutes
-user aliceowned by alice
-perm 644with this exact mode
-emptyempty

Combine with -and, -or and !.

find . -type f -name "*.log" -mtime +30
find . -type f \( -name "*.js" -o -name "*.ts" \) -size +1M
find . -type f ! -name "*.md"

-maxdepth limits the recursion, which is a large speedup.

find . -maxdepth 2 -name "*.json"

Acting on the results

-exec runs a command per file.

find . -name "*.tmp" -exec rm {} \;

{} is the file, and \; ends the command. The + form batches several files into one invocation, which is faster.

find . -name "*.log" -exec gzip {} +

-delete removes the matches, and it is faster than -exec rm.

find . -name "*.tmp" -delete

The caution: -delete acts on whatever the criteria match. Run the same find without -delete first to see the list.

-print0 and xargs -0 handle a filename with a space.

find . -name "*.log" -print0 | xargs -0 gzip

A plain xargs splits on whitespace, so a filename with a space becomes two arguments. The null-delimited form is the safe one.

Combining find and grep

The pattern that is worth remembering: find selects the files, grep searches inside them.

find src -type f -name "*.ts" -exec grep -l "TODO" {} +

Or with xargs.

find src -type f -name "*.ts" -print0 | xargs -0 grep -l "TODO"

grep -r is simpler for the common case, and the find-and-grep combination is for when the file selection is more complex than a directory and an extension.

Why the shell tools still matter

A graphical tool is faster for a one-off search, and the shell tools are faster for a search that has to be repeated, scripted, or run on a server. The reason is composition: grep and find read from a pipe and write to one, so they combine with each other and with any other tool. A search that starts as an interactive command becomes a script by adding a loop, and the same script runs in a CI job without a change. The second reason is that the tools are present everywhere. A container image, a build server, and a minimal server install all have grep and find, and a tool that must be installed is a tool that is not available when it is needed most. The third reason is precision: a regular expression and a set of criteria express a search that a graphical tool cannot, and the result is reproducible.

A search strategy

A search is most effective when it narrows in stages rather than starting with the most specific pattern. The first stage is to find the files, which is a find with a name, a type and a directory limit. The second is to search inside them, which is a grep with a fixed string and a file list. The third is to narrow the result, which is a grep with a line number and a context, or a pipe to a second filter. The fourth is to confirm the match, which is to open the file at the line the search reported. The reason to work in stages is that a broad search is fast and a narrow one is slow, and a search that starts narrow often misses the file because the assumption about the name or the directory was wrong. A search that starts broad and narrows finds the answer even when the first assumption is incorrect, which is the common case in an unfamiliar codebase.

Common mistakes

A recursive grep without exclusions. It searches node_modules and .git, which is slow and noisy.

Piping find to a plain xargs. A filename with a space is split. Use -print0 and xargs -0.

find -delete without checking the criteria first. It removes whatever matches. Run the find without the action first.

A pattern with an unescaped special character. Use -F for a literal, or escape the character.

grep on a binary file. The output is unreadable. Use -I to skip binaries, or -a to treat them as text.

find on / without a limit. It traverses the whole filesystem, including the virtual filesystems. Limit the path and the depth.

Assuming -name is case-insensitive. It is not. Use -iname.

A quotable summary

grep searches file contents and find searches the filesystem, and the two are often combined: find selects the files and grep searches inside them. Use grep -r with --include and --exclude-dir to keep a recursive search fast, and -l when you want the file names rather than the lines. Use find with -name, -type, -size and -mtime to select files, and prefer -print0 with xargs -0 over a plain pipe so a filename with a space is handled correctly.

For the shell around this, see linux-command-line-basics and for the JSON tool, jq-json-command-line. For the broader context, bash-scripting-basics and linux-file-permissions.

Frequently asked questions

What is the difference between grep and find?
grep searches the contents of files for a pattern. find searches the filesystem for files that match criteria such as a name, a size or a modification time. They are often combined: find selects the files, and grep searches inside them.
How do I search recursively with grep?
Use grep -r pattern path. Add -i for a case-insensitive match, -n to show the line number, and -l to list only the file names. To exclude a directory, use --exclude-dir, which is faster than searching it and filtering afterwards.
What is the difference between find -exec and xargs?
find -exec runs the command once per file and handles a filename with a space correctly. Piping to xargs is faster because it batches, but it splits on whitespace unless you use -print0 and xargs -0. Use -exec for a small set and the null-delimited form for a large one.
How do I find files modified in the last day?
Use find path -mtime -1. The -mtime is in days, and a negative value means less than that many days ago. For minutes, use -mmin, so -mmin -60 is the last hour. Add -type f to match only files.
How do I search for a literal string that contains a special character?
Use grep -F for a fixed string, which treats the pattern as a literal rather than a regular expression. It is also faster, because it does not compile a pattern. For a pattern that starts with a dash, use -- to end the options.
Why is my grep so slow on a large directory?
It is searching binary files and directories that do not matter. Use --include to limit the file types, --exclude-dir to skip node_modules and .git, and -I to skip binary files. A targeted search is often an order of magnitude faster.