git exit codes an agent can rely on: diff --exit-code, ls-remote --exit-code, and bisect run's 125

What it is

Git's own documentation does not publish one universal exit-status table for every command — most porcelain commands (push, commit, checkout) only say "fails with non-zero status" in prose. Three commands are the exception, with a precise, documented contract an agent can branch on directly:

Command	0	1	Other
git diff --exit-code / --quiet	no differences	there were differences	—
git ls-remote --exit-code	talked to the remote successfully (refs found, or none requested)	—	2 = no matching refs found in the remote repository
git bisect run <script>	(script's own 0) current revision is good/old	1–127 except 125: current revision is bad/new	125 = cannot test, skip this revision; any other code aborts the bisect

git diff's --exit-code option "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 implies --exit-code and additionally suppresses output. 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" regardless of whether any refs matched. git bisect run's documentation is explicit that "the special exit code 125 should be used when the current source code cannot be tested," precisely because 126 and 127 are already claimed by the shell for "found but not executable" and "not found."

Why it matters

Git bisect's 125 is the sharpest trap: a bisect-run script that exits 125 is not reporting a bug in the revision under test, it is asking git to skip that revision entirely — treating 125 the same as any other non-zero ("bad") will corrupt the bisect search.

How to apply

• Use git diff --quiet (or --exit-code) in CI/pre-commit checks precisely because 0/1 is a documented, stable contract — don't parse diff output to detect "no changes."
• Use git ls-remote --exit-code <remote> <ref> to check whether a tag/branch exists on a remote without cloning; branch on exit 2 specifically for "not found," not on any non-zero.
• Reserve exit 125 in bisect run scripts strictly for "cannot determine good/bad here" (build failure unrelated to the bug), and any other non-zero for a genuine "bad."
• For git merge, do not hard-code an expected conflict exit code; git's own documentation only says "a merge stops if there's a conflict that cannot be resolved automatically." Detect a stopped merge by checking for .git/MERGE_HEAD or unmerged paths in git status --porcelain, not by a specific number.

Pitfalls

• Assuming a general "128 = fatal, 129 = usage error" rule applies uniformly across all git subcommands; git's documentation does not publish that as a stable, command-independent contract, so treat it as convention at best.
• Wrapping git bisect run in a harness that maps "any non-zero equals bad" silently breaks the skip mechanism.
• git status has no --exit-code option. git diff --quiet ignores staged changes (add git diff --cached --quiet) and untracked files (check that git status --porcelain prints nothing).