grep, diff, cmp e test/[: o código de saída 1 significa «não encontrado», não falha

O que é

Quatro das ferramentas que um agente mais chama pela linha de comando seguem uma mesma convenção, fácil de interpretar mal: um código de saída diferente de zero nem sempre significa que a ferramenta falhou.

Ferramenta	0	1	2 (ou >1)
grep	uma linha foi selecionada	nenhuma linha foi selecionada	ocorreu um erro
diff	as entradas são iguais	as entradas diferem	problema (caminho inválido, arquivo ilegível)
cmp	os arquivos são idênticos	os arquivos diferem	problema
test / [	a expressão é verdadeira	a expressão é falsa ou está ausente	ocorreu um erro

O manual do GNU grep afirma que o status de saída é "0 se uma linha for selecionada, 1 se nenhuma linha for selecionada e 2 se ocorrer um erro". O manual do diffutils dá a diff e cmp a mesma divisão em três: "0 se as entradas forem iguais, 1 se forem diferentes, 2 se houver problema". O POSIX define test/[ de forma idêntica: 0 para verdadeiro, 1 para falso (ou expressão ausente) e qualquer valor acima de 1 para um erro de fato.

Por que importa

Nas quatro ferramentas, o código 1 é o resultado esperado em grande parte das execuções: uma busca sem ocorrências, dois arquivos que diferem, uma condição falsa. Um agente que trata "diferente de zero" como "o comando falhou" vai reportar um resultado negativo normal como etapa quebrada do pipeline. Pior: pode deixar de perceber quando o código é, na verdade, 2 (ou maior), que é a ferramenta avisando que nem conseguiu concluir a comparação — sintaxe de padrão errada, arquivo ilegível, um diretório onde se esperava um arquivo.

Como aplicar

• Decida com base no valor específico, e não em "zero ou não zero": trate 1 como uma resposta negativa normal e reserve o tratamento de falha para 2 (grep/diff/cmp) ou qualquer valor acima de 1 (test).
• Com grep -q/--quiet, atente para a ressalva do manual: se houver correspondência, o código continua sendo 0 mesmo que tenha ocorrido um erro não relacionado ao ler outro arquivo. Não use apenas o código de saída de -q como prova de que todas as entradas puderam ser lidas.
• Para diff/cmp em um pipeline que deve falhar de forma explícita diante de um erro real, mas tolerar diferenças, verifique $? -gt 1 (ou -eq 2) em vez de $? -ne 0.
• Para [ … ] no bash, lembre que uma expressão malformada ("unary operator expected", um ] faltando) retorna 2, não 1; colocar as variáveis entre aspas ("$var") evita a maioria desses casos.

Armadilhas

• Envolver qualquer uma dessas ferramentas em um tratamento de erro do tipo command || exit 1 elimina a distinção útil entre "não" e "quebrado".
• Presumir que outras implementações (o grep do busybox, algumas reimplementações do diff) mantêm exatamente 0/1/2. O texto do POSIX e do GNU citado acima descreve a base comum, não todos os clones.