Códigos de salida de git en los que un agente puede confiar: diff --exit-code, ls-remote --exit-code y el 125 de bisect run

Qué es

La documentación de Git no publica una tabla universal de códigos de salida para todos los comandos: la mayoría de los comandos porcelain (push, commit, checkout) solo indican en prosa que "fails with non-zero status" (fallan con un estado distinto de cero). Tres comandos son la excepción, con un contrato preciso y documentado sobre el que un agente puede ramificar su lógica directamente:

Comando	0	1	Otro
git diff --exit-code / --quiet	no hay diferencias	hubo diferencias	—
git ls-remote --exit-code	se comunicó con el remoto correctamente (se encontraron refs, o no se pidió ninguna)	—	2 = no se encontraron refs coincidentes en el repositorio remoto
git bisect run <script>	(el 0 del propio script) la revisión actual es good/old	1–127 excepto 125: la revisión actual es bad/new	125 = no se puede probar, omitir esta revisión; cualquier otro código aborta el bisect

La opción --exit-code de 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." --quiet implica --exit-code y además suprime la salida. 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", sin importar si alguna ref coincidió. La documentación de git bisect run es explícita: "the special exit code 125 should be used when the current source code cannot be tested", precisamente porque el shell ya reserva el 126 y el 127 para "found but not executable" (encontrado pero no ejecutable) y "not found" (no encontrado).

Por qué importa

El 125 de git bisect es la trampa más peligrosa: un script de bisect run que termina con 125 no está informando de un error en la revisión que se prueba, sino pidiéndole a git que omita esa revisión por completo. Tratar el 125 igual que cualquier otro código distinto de cero ("bad") corrompe la búsqueda del bisect.

Cómo aplicarlo

• Usa git diff --quiet (o --exit-code) en las comprobaciones de CI o pre-commit, precisamente porque 0/1 es un contrato documentado y estable: no analices la salida de diff para detectar que "no hay cambios".
• Usa git ls-remote --exit-code <remote> <ref> para comprobar si un tag o una rama existe en un remoto sin clonar; ramifica específicamente con el código 2 para "no encontrado", no con cualquier valor distinto de cero.
• Reserva el código 125 en los scripts de bisect run estrictamente para "aquí no se puede determinar si es good o bad" (un fallo de compilación ajeno al error buscado), y cualquier otro valor distinto de cero para un "bad" genuino.
• Con git merge, no codifiques de forma fija un código de salida esperado para los conflictos; la propia documentación de git solo dice que "a merge stops if there's a conflict that cannot be resolved automatically". Detecta un merge detenido comprobando si existe .git/MERGE_HEAD o si hay rutas sin fusionar en git status --porcelain, no mediante un número concreto.

Trampas

• Suponer que una regla general como "128 = fatal, 129 = error de uso" se aplica de manera uniforme a todos los subcomandos de git; la documentación de git no la publica como un contrato estable e independiente del comando, así que, como mucho, trátala como una convención.
• Envolver git bisect run en un arnés que asigna "cualquier valor distinto de cero equivale a bad" rompe en silencio el mecanismo de omisión.
• git status no tiene la opción --exit-code. git diff --quiet ignora los cambios en el área de preparación (añade git diff --cached --quiet) y los archivos sin seguimiento (comprueba que git status --porcelain no imprima nada).