← back to latest

Find the files that mention one thing but never mention another

grep -rl --null --include='*.js' 'fetch(' . | xargs -0 -r grep -L 'catch'

anatomy

grep -r
Search every file under the starting directory. GNU grep's -r skips symlinks it meets along the way; -R follows them.
-l
Print only the names of files that match, once each, and stop reading a file at its first hit. This turns grep from a line finder into a file filter, which is what the second stage needs as input.
--null
End each filename with a zero byte instead of a newline. Zero is the only byte a Unix filename cannot contain, so this is the one separator a space, quote, or newline in a name cannot break. GNU grep also spells it -Z, but on macOS -Z means something else, so the long form is the portable one.
--include='*.js'
Only look at files whose name matches the glob. The quotes matter: unquoted, the shell expands *.js against the current directory before grep ever sees it.
'fetch('
The first condition. In grep's default basic regex syntax a bare ( is a literal character, so this matches the text fetch( and not a group. Under -E you would need fetch\(.
xargs -0
Read zero-terminated names from the pipe and pass them as arguments to the command that follows, batching as many as fit on one command line.
-r
Do not run the command at all if the input is empty. Without it GNU xargs runs grep once with no filenames, and grep falls back to reading standard input.
grep -L 'catch'
The inverse of -l: print the names of files that contain no match at all. Applied to the survivors of the first grep, it leaves the files that call fetch and never mention catch.

Sample output

$ grep -rl --null --include='*.js' 'fetch(' . | xargs -0 -r grep -L 'catch'
./src/routes/users.js
./src/routes/order history.js

Four files in this project make network calls, and these two have no error handling anywhere in them. The space in order history.js came through intact because the names travelled between the two greps as zero-terminated strings, not as words.

When you would reach for it

Any audit that is really a question about absence: source files that call an API but never handle its failure, modules that import a library but are missing the license header, config files that set a timeout but no retry. A single grep answers “where does X appear” and cannot answer “where does X appear without Y”, because the second condition is about the whole file, not a line. Chaining a file-name filter into an inverse file-name filter gives you that set operation without writing a script.

Gotchas

  • Leave out the -r on xargs and a first grep that finds nothing still runs the second one, with no filenames. grep then reads standard input, which GNU xargs points at /dev/null, finds no match there, and prints (standard input) as a result. On macOS, xargs already skips empty input and accepts -r for compatibility, so the same command works on both.
  • grep -L sets its exit status by whether any line matched, not by whether it printed a filename. With GNU grep 3.8, the version on Debian 12, it exits 1 when every file it was given is listed and 0 when at least one file had a match, so grep -L catch file.js && echo missing prints the opposite of what it says. A few GNU releases around 2018 to 2020 briefly flipped this. Test the output, not $?.
  • Without --null and -0, xargs splits on whitespace, and order history.js arrives as two files called order and history.js. You get two No such file or directory errors and, worse, a file silently missing from the answer.
  • The test is per file and purely textual. A file whose only catch is in a comment, or that handles errors in a different function from the one making the call, counts as handled. Treat the result as a short list to read, not a verdict.

Variants

$ grep -rl --null 'fetch(' . | xargs -0 grep -l --null 'json' | xargs -0 -r grep -L 'catch'

Add a condition by adding a stage. Every middle stage uses -l --null so it can feed the next, and only the last one switches to -L

$ git grep -lz 'fetch(' -- '*.js' | xargs -0 -r grep -L 'catch'

Inside a repository, search only tracked files. git grep skips anything in .gitignore, so node_modules and build output stay out of the results without a long list of exclusions

$ grep -rL --include='*.js' 'SPDX-License-Identifier' .

The one-condition case needs no pipeline. Every JavaScript file missing a license header, listed directly

lineage

grep began as a command inside ed, the Unix line editor: g/re/p, globally search for a regular expression and print. Ken Thompson pulled it out into its own program in the early 1970s, and by the commonly told story he did it overnight because Doug McIlroy wanted to search files too large for the editor. xargs arrived a few years later in PWB/UNIX, Bell Labs' Programmer's Workbench, to work around the limit on how long a command line can be. The zero-byte handoff came much later: GNU findutils added find -print0 and xargs -0 as a pair, after years of scripts breaking on filenames with spaces in them, and other tools, grep included, grew matching options so they could take part in the same pipelines.