Git-Exit-Codes, auf die sich ein Agent verlassen kann: diff --exit-code, ls-remote --exit-code und die 125 bei bisect run

Worum es geht

Die Git-Dokumentation enthält keine einheitliche Tabelle der Exit-Status-Werte für alle Befehle. Bei den meisten Porcelain-Befehlen (push, commit, checkout) steht im Fliesstext lediglich "fails with non-zero status". Drei Befehle bilden die Ausnahme: Sie haben einen präzisen, dokumentierten Vertrag, auf den ein Agent direkt verzweigen kann:

Befehl	0	1	Sonstige
git diff --exit-code / --quiet	keine Unterschiede	es gab Unterschiede	—
git ls-remote --exit-code	Kommunikation mit dem Remote erfolgreich (Refs gefunden oder keine angefragt)	—	2 = keine passenden Refs im Remote-Repository gefunden
git bisect run <script>	(eigene 0 des Skripts) aktuelle Revision ist good/old	1–127 ausser 125: aktuelle Revision ist bad/new	125 = nicht testbar, diese Revision überspringen; jeder andere Code bricht die Bisect-Suche ab

Zur Option --exit-code von git diff heisst es: "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 impliziert --exit-code und unterdrückt zusätzlich die Ausgabe. Für git ls-remote --exit-code gilt: Der Befehl "exit[s] with status 2 when no matching refs are found in the remote repository. Usually the command exits with status 0", unabhängig davon, ob Refs gefunden wurden. Die Dokumentation von git bisect run hält ausdrücklich fest: "the special exit code 125 should be used when the current source code cannot be tested". Der Grund: 126 und 127 sind bereits von der Shell belegt, für "found but not executable" und "not found".

Warum es wichtig ist

Die 125 bei Git bisect ist die gefährlichste Falle: Ein Skript für bisect run, das mit 125 endet, meldet keinen Fehler in der getesteten Revision, sondern fordert Git auf, diese Revision ganz zu überspringen. Wird 125 wie jeder andere Wert ungleich null ("bad") behandelt, wird die Bisect-Suche verfälscht.

So wird es angewendet

• git diff --quiet (oder --exit-code) in CI- und Pre-Commit-Prüfungen verwenden, gerade weil 0/1 ein dokumentierter, stabiler Vertrag ist. Die Ausgabe von diff nicht auswerten, um "keine Änderungen" zu erkennen.
• Mit git ls-remote --exit-code <remote> <ref> prüfen, ob ein Tag oder Branch auf einem Remote existiert, ohne zu klonen. Für "nicht gefunden" gezielt auf Exit-Code 2 verzweigen, nicht auf irgendeinen Wert ungleich null.
• Exit-Code 125 in Skripten für bisect run ausschliesslich für "gut/schlecht lässt sich hier nicht bestimmen" reservieren (etwa ein Build-Fehler, der nichts mit dem Bug zu tun hat); jeden anderen Wert ungleich null nur für ein echtes "bad" verwenden.
• Bei git merge keinen bestimmten Exit-Code für Konflikte fest verdrahten. Die Git-Dokumentation sagt nur: "a merge stops if there's a conflict that cannot be resolved automatically." Einen angehaltenen Merge über das Vorhandensein von .git/MERGE_HEAD oder über nicht zusammengeführte Pfade in git status --porcelain erkennen, nicht über eine bestimmte Zahl.

Stolpersteine

• Die Annahme, dass eine allgemeine Regel "128 = fatal, 129 = Aufruffehler" einheitlich für alle Git-Unterbefehle gilt. Die Git-Dokumentation legt das nicht als stabilen, befehlsunabhängigen Vertrag fest; es ist bestenfalls eine Konvention.
• git bisect run in einen Wrapper einzubinden, der "jeder Wert ungleich null ist bad" abbildet, setzt den Skip-Mechanismus unbemerkt ausser Kraft.
• git status hat keine Option --exit-code. git diff --quiet ignoriert gestagte Änderungen (dafür git diff --cached --quiet ergänzen) und nicht verfolgte Dateien (prüfen, ob git status --porcelain nichts ausgibt).