grep, diff, cmp and test/[: exit code 1 means not-found, not failure

What it is

Four of the most common tools an agent shells out to share one convention that is easy to misread: a non-zero exit code does not always mean the tool failed.

Tool	0	1	2 (or >1)
grep	a line was selected	no lines were selected	an error occurred
diff	inputs are the same	inputs differ	trouble (bad path, unreadable file)
cmp	files are identical	files differ	trouble
test / [	expression is true	expression is false or missing	an error occurred

The GNU grep manual states the exit status is "0 if a line is selected, 1 if no lines were selected, and 2 if an error occurred." The diffutils manual gives diff and cmp the same three-way split: "0 if inputs are the same, 1 if different, 2 if trouble." POSIX defines test/[ identically: 0 true, 1 false (or a missing expression), and any value above 1 for a genuine error.

Why it matters

In all four tools, exit code 1 is the expected outcome of a large fraction of invocations — a search with no hits, two files that differ, a false condition. An agent that treats "non-zero" as "command failed" will misreport a normal negative result as a broken pipeline step, and worse, may fail to notice when the code is actually 2 (or greater), which is the tool telling you it could not even complete the comparison — wrong pattern syntax, unreadable file, a directory where a file was expected.

How to apply

• Branch on the specific value, not on "zero or not": treat 1 as a normal negative answer and reserve failure handling for 2 (grep/diff/cmp) or anything above 1 (test).
• With grep -q/--quiet, note the manual's caveat: a match found still reports 0 even if an unrelated error occurred reading another file — don't rely on -q's exit code alone to prove every input was readable.
• For diff/cmp in a pipeline that should fail loudly on a real error but tolerate differences, check $? -gt 1 (or -eq 2) rather than $? -ne 0.
• For [ … ] in bash, remember a malformed expression ("unary operator expected", a missing ]) returns 2, not 1 — quoting variables ("$var") prevents most of these.

Pitfalls

• Wrapping any of these tools in command || exit 1 style error handling collapses the useful distinction between "no" and "broken."
• Assuming other implementations (busybox grep, some diff reimplementations) keep exactly 0/1/2; the POSIX and GNU text above describes the common baseline, not every clone.