Códigos de saída do git em que um agente pode confiar: diff --exit-code, ls-remote --exit-code e o 125 do bisect run

O que é

A documentação do próprio git não publica uma tabela única de códigos de saída para todos os comandos: a maioria dos comandos porcelain (push, commit, checkout) diz apenas, em texto corrido, que "fails with non-zero status" (falha com status diferente de zero). Três comandos são exceção, com um contrato preciso e documentado, no qual um agente pode basear diretamente a sua lógica de decisão:

Comando	0	1	Outros
git diff --exit-code / --quiet	sem diferenças	houve diferenças	—
git ls-remote --exit-code	comunicação com o remoto bem-sucedida (refs encontradas, ou nenhuma solicitada)	—	2 = nenhuma ref correspondente encontrada no repositório remoto
git bisect run <script>	(0 do próprio script) a revisão atual é boa/antiga	1–127, exceto 125: a revisão atual é ruim/nova	125 = não é possível testar, ignorar esta revisão; qualquer outro código aborta o bisect

A opção --exit-code do git diff "makes the program exit with codes similar to diff(1). That is, it exits with 1 if there were differences and 0 means no differences." O --quiet implica --exit-code e, além disso, suprime a saída. O git ls-remote --exit-code "exit[s] with status 2 when no matching refs are found in the remote repository. Usually the command exits with status 0", independentemente de alguma ref ter correspondido. A documentação do git bisect run é explícita: "the special exit code 125 should be used when the current source code cannot be tested", justamente porque o shell já reserva o 126 e o 127 para "encontrado, mas não executável" e "não encontrado".

Por que importa

O 125 do git bisect é a armadilha mais perigosa: um script de bisect run que termina com 125 não está relatando um bug na revisão testada, está pedindo ao git que ignore essa revisão por completo. Tratar o 125 como qualquer outro código diferente de zero ("ruim") corrompe a busca do bisect.

Como aplicar

• Use git diff --quiet (ou --exit-code) em verificações de CI/pre-commit justamente porque 0/1 é um contrato documentado e estável; não analise a saída do diff para detectar "sem alterações".
• Use git ls-remote --exit-code <remote> <ref> para verificar se uma tag/branch existe em um remoto sem clonar; trate especificamente o código 2 como "não encontrado", e não qualquer código diferente de zero.
• Reserve o código 125 nos scripts de bisect run estritamente para "não é possível determinar se está bom ou ruim aqui" (falha de build não relacionada ao bug), e qualquer outro código diferente de zero para um "ruim" genuíno.
• No caso de git merge, não fixe no código um código de saída esperado para conflito; a documentação do git diz apenas que "a merge stops if there's a conflict that cannot be resolved automatically." Detecte um merge interrompido verificando a existência de .git/MERGE_HEAD ou de caminhos não mesclados (unmerged) em git status --porcelain, e não por um número específico.

Armadilhas

• Presumir que a regra geral "128 = erro fatal, 129 = erro de uso" vale de modo uniforme para todos os subcomandos do git; a documentação do git não a publica como contrato estável e independente do comando, portanto, no máximo, trate-a como convenção.
• Envolver o git bisect run em um harness que mapeia "qualquer código diferente de zero = ruim" quebra silenciosamente o mecanismo de skip.
• O git status não tem a opção --exit-code. O git diff --quiet ignora alterações em stage (adicione git diff --cached --quiet) e arquivos não rastreados (verifique se git status --porcelain não imprime nada).