Codes de sortie de git fiables pour un agent : diff --exit-code, ls-remote --exit-code et le code 125 de bisect run

Ce que c'est

La documentation de git ne publie pas de table unique des codes de sortie couvrant toutes les commandes : pour la plupart des commandes porcelain (push, commit, checkout), elle se limite à dire en prose "fails with non-zero status" (échoue avec un code non nul). Trois commandes font exception, avec un contrat précis et documenté sur lequel un agent peut s'appuyer directement pour ses branchements :

Commande	0	1	Autre
git diff --exit-code / --quiet	aucune différence	il y avait des différences	—
git ls-remote --exit-code	communication réussie avec le dépôt distant (références trouvées, ou aucune demandée)	—	2 = aucune référence correspondante trouvée dans le dépôt distant
git bisect run <script>	(0 renvoyé par le script) la révision courante est bonne/ancienne	1–127 sauf 125 : la révision courante est mauvaise/nouvelle	125 = test impossible, ignorer cette révision ; tout autre code interrompt le bisect

L'option --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." (le programme se termine avec des codes similaires à ceux de diff(1) : 1 s'il y a des différences, 0 s'il n'y en a pas). --quiet implique --exit-code et supprime en plus la sortie. 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" (se termine avec le code 2 si aucune référence correspondante n'est trouvée dans le dépôt distant ; en temps normal, la commande renvoie 0), que des références aient correspondu ou non. La documentation de git bisect run est explicite : "the special exit code 125 should be used when the current source code cannot be tested," (le code spécial 125 doit être utilisé quand le code source courant ne peut pas être testé), précisément parce que 126 et 127 sont déjà employés par le shell pour « trouvé mais non exécutable » et « introuvable ».

Pourquoi c'est important

Le 125 de git bisect est le piège le plus redoutable : un script de bisect run qui se termine avec 125 ne signale pas un bogue dans la révision testée, il demande à git d'ignorer complètement cette révision. Traiter 125 comme n'importe quel autre code non nul (« mauvais ») corrompt la recherche du bisect.

Comment l'appliquer

• Utiliser git diff --quiet (ou --exit-code) dans les contrôles de CI ou de pre-commit, justement parce que 0/1 est un contrat documenté et stable : ne pas analyser la sortie de diff pour détecter l'absence de changements.
• Utiliser git ls-remote --exit-code <remote> <ref> pour vérifier qu'un tag ou une branche existe sur un dépôt distant sans cloner ; tester spécifiquement le code 2 pour « introuvable », et non n'importe quel code non nul.
• Réserver le code 125 dans les scripts bisect run strictement au cas « impossible de déterminer ici si c'est bon ou mauvais » (échec de build sans rapport avec le bogue), et tout autre code non nul à un véritable « mauvais ».
• Pour git merge, ne pas coder en dur un code de sortie attendu en cas de conflit : la documentation de git dit seulement "a merge stops if there's a conflict that cannot be resolved automatically." (un merge s'arrête s'il y a un conflit qui ne peut pas être résolu automatiquement). Détecter un merge interrompu en vérifiant la présence de .git/MERGE_HEAD ou de chemins non fusionnés dans git status --porcelain, et non via un numéro précis.

Pièges

• Supposer qu'une règle générale « 128 = erreur fatale, 129 = erreur d'usage » s'applique uniformément à toutes les sous-commandes de git : la documentation de git ne la publie pas comme un contrat stable et indépendant de la commande, il faut donc la considérer au mieux comme une convention.
• Encapsuler git bisect run dans un harnais qui traduit « tout code non nul = mauvais » casse silencieusement le mécanisme permettant d'ignorer des révisions.
• git status n'a pas d'option --exit-code. git diff --quiet ignore les changements indexés (ajouter git diff --cached --quiet) et les fichiers non suivis (vérifier que git status --porcelain n'affiche rien).