Grit uses a small set of exit codes. Command-specific yes/no checks (for example grit diff --exit-code) reuse failure (1) when the answer is “no”. See Scripting with grit and the Agent guide for --json behavior.
Exit status
| Slug | Code | Meaning |
|---|---|---|
success |
0 | Command completed successfully (including some checks that answer “yes”). |
failure |
1 | Command failed, or a yes/no check answered “no” (diff --exit-code, merge --check, pick --check, revert --check, pull --check, merge-base --is-ancestor, fsck, ignore check, tag --verify, conflicts after merge / pick / revert / rebase, rejected push, and similar). With --json, stdout is usually {"error":"…"} or a full outcome object when the failure is part of the result (for example rejected push). |
usage |
2 | Invalid flags or arguments. With --json, stdout is still {"error":"…"} (clap usage errors and subcommand usage such as grit branch). Hunk selection mistakes (add / commit / stash / restore with unknown or stale --hunks ids) also exit 2. grit diff --exit-code / --quiet uses 2 when diff itself errors. |
needs_decision |
3 | grit push or grit sync did its work, but another member's head of a shared branch diverged from yours in a way someone has to decide about. The output (shared[].heads[].divergence in --json) names the scenario and what each side did; nothing is lost, since the server keeps every head. Scripts and agents should read the report rather than retry. |
remote_unreadable |
128 | clone, fetch, pull, push, or remote refs could not reach or read the remote: a missing repository path, a DNS, refused-connection, TLS, or timeout failure, an HTTP error status, or a transport that never spoke Git. With --json, stdout is {"error":"…","kind":"remote_unreadable"}. Rejected pushes and authentication failures are not in this class (they exit 1). |
missing_prerequisite |
128 | grit bundle unbundle when the repository lacks prerequisite commits. |
refused_not_ff |
128 | grit merge --ff-only or grit pull --ff-only when a fast-forward is not possible. |
invalid_commit_filter |
129 | Invalid --author, --grep, or pickaxe pattern on grit log, grit revs, or related commands (kind: invalid_pattern). |
interrupted |
130 | grit clone, grit fetch, or grit push stopped by Ctrl-C, SIGTERM, or SIGHUP on Unix (or Ctrl-Break on Windows). Partial work is rolled back (for example an incomplete clone directory, fetch temp pack, or push receive quarantine on the remote), so the same command can be run again. With --json, stdout is {"error":"operation cancelled"}. |
custom |
varies | Passthrough from grit hooks run (hook exit code) or grit rebase --exec when a command fails. |
Structured error kinds (kind in JSON)
These values appear in the kind field of structured --json errors (error schema). Plain failures omit kind.
When grit knows what to do next, the object also has a hint naming the command to run, and human output prints the same text on a hint: line after the error: line (Markdown output adds a **Hint:** paragraph). Failures about specific files list them in paths (or conflicts / would_overwrite.paths).
$ grit push
error: no remote to push to
hint: add one with `grit remote add origin <url>`, or push to a URL with `grit push <url> <branch>`
$ grit push --json
{"error":"no remote to push to","hint":"add one with `grit remote add origin <url>`, or push to a URL with `grit push <url> <branch>`","kind":"no_remote"}
| Slug | When |
|---|---|
conflict |
Merge, pick, rebase, or similar would introduce conflicts (conflicts, optional commit). A grit history rewrite or grit rebase that fails replaying another branch it would move also sets refs (full branch names) and a hint to pass --update-refs head. |
hash_collision |
Refusing to store content that triggers SHA-1 collision detection (oid). |
would_overwrite |
Checkout, switch, merge, or pull would overwrite local or untracked files (would_overwrite.reason, would_overwrite.paths). The hint suggests grit commit or grit stash for local changes. |
operation_in_progress |
grit switch refused while a merge, rebase, pick or revert is paused (grit's or one git started); finish or abort it first. |
invalid_pattern |
Invalid filter pattern (exit 129). |
usage |
Subcommand usage mistake (exit 2), e.g. grit branch flag combinations. |
incompatible_flags |
Flags that cannot be combined (often --json with human-only options). |
lock_held |
A lock file such as .git/index.lock or refs/heads/main.lock already exists (exit 1). The lock file is left alone on ordinary commands. Staging and committing stop before changing the index or recording a commit; retry after the holder finishes. lock.path names the lock, and lock.holder.pid / lock.holder.running are present when grit wrote a pid sidecar (default for grit-owned index locks; set core.lockfilePid=false to opt out). When lock.holder.running is false, the lock is stale; interrupted rewrite recovery removes it automatically on the next status or abort. |
index_locked |
Deprecated alias of lock_held, emitted by v0.5.21 for a held index lock. grit no longer emits it; it stays in the error schema for one release so v0.5.21 output still validates, then it is removed. Match lock_held instead. |
branch_already_exists |
Create branch when the name already exists. |
branch_not_found |
Branch name not found. grit switch hints at grit branch and grit switch -c <name>. |
no_previous_branch |
grit switch - when HEAD has no earlier checkout in the reflog. |
branch_invalid_name |
Invalid branch name. |
branch_not_fully_merged |
Delete refused: not fully merged. |
branch_checked_out |
Branch checked out in this or another worktree. |
branch_no_commits |
No commits in repository. |
branch_invalid_start_point |
Invalid --start / start point. |
branch_upstream_not_tracking |
Upstream is not a tracking branch. |
branch_no_upstream |
No upstream configured. grit pull hints at grit pull origin <branch> and grit push -u origin <branch>. |
branch_error |
Other branch operation failure. |
hook_failed |
A hook such as pre-commit exited non-zero (hook.name, hook.status, and the hook's captured hook.stdout / hook.stderr). |
revision_not_found |
A branch, tag, commit id or revision expression names nothing. Any command that resolves a revision may emit this kind when the spec names nothing (not only grit merge). |
remote_unreadable |
The remote could not be reached or read (exit 128); see the exit status table above. When the server answers 404, the hint asks you to check the URL. |
no_remote |
grit push with no remote named, no push remote for the branch, and no origin. Hint: grit remote add origin <url>. |
remote_not_found |
A remote name that is not configured (grit push origin main, grit pull, grit fetch nosuch). Hint: grit remote add <name> <url>. |
remote_no_url |
The remote is configured but has no URL. Hint: grit remote set-url <name> <url>. |
auth_required |
An HTTPS remote wants credentials and neither a credential helper nor an askpass program (GIT_ASKPASS, core.askPass, SSH_ASKPASS) supplied them. The error names the repository URL; the hint is grit auth for github.com, otherwise a credential.helper or GIT_ASKPASS. |
auth_rejected |
The remote refused the credentials that were sent. |
unmerged_paths |
grit merge --continue while conflicts are unresolved, or resolved but not staged with commit.autoStage=false (paths). The hint names the files and grit merge --continue / grit merge --abort (or grit add). Also a plain or --staged grit restore of a conflicted path; the hint names grit restore --ours / --theirs / --merge and grit add. Also grit add / grit commit when a file still has conflict markers after its conflict stages were dropped, for example by git restore --staged after a merge, pick or stash pop (paths); the hint says to edit out the markers. |
dirty_worktree |
Staged or unstaged changes block a merge, pick, revert, switch or rebase --exec (paths). Hint: grit commit or grit stash. |
worktree_path_io |
Checkout, stash, add, diff, or reset could not read or replace a worktree file (paths, often one path). Typical causes: another program has the file open, or a permission problem. The hint to close the program and retry appears only when the operating system reports the file as in use. |
checkout_incomplete |
A switch or checkout stopped part way (cancelled with Ctrl+C, or failed) and could not put some work-tree paths back (paths). HEAD and the index did not move; only the listed paths differ. Hint: grit reset --hard and grit clean -f. |
clone_checkout_failed |
grit clone downloaded every object and set up the refs, but checking out the work tree failed (exit 1), usually because a partial clone could not fetch its missing blobs. The repository is kept, as git clone keeps it; clone_checkout has path, commit, missing_object (when a promised object was missing) and failed_remotes (remote, error). Hint: run grit reset --hard in the clone to finish the checkout. |
git_dir_path_io |
Commit, gc, or ref update could not write under .git/ (paths, often one path such as .git/objects or .git/refs/heads/main). Typical causes: read-only or root-owned .git metadata, or another thread/process updating the same index or ref (Windows often reports this as the file being in use). Hint: for permission problems check ls -l .git and fix ownership; when the message says the file is in use, retry after the other updater finishes. |
nothing_staged |
grit commit with commit.autoStage=false or --staged while the index matches HEAD but the work tree has unstaged or untracked paths. Hint: grit add or grit commit -- <path>. |
nothing_to_commit |
grit commit on a genuinely clean tree (or after auto-staging cancels out against HEAD). |
not_a_repository |
Command run outside any Git repository (or parent directory). |
commit_message_required |
grit commit without -m, -F, amend/reuse, or a pending merge message. |
empty_commit_message |
grit commit -m '', empty -F, or a hook that cleared the message. |
identity_unknown |
Author or committer identity could not be resolved (hint names grit config --global user.name / user.email). |
tag_already_exists |
Create tag when the name already exists (hint mentions --force). |
tag_not_found |
Delete or verify a tag when refs/tags/<name> does not exist. |
no_operation_in_progress |
merge --abort, rebase --continue, pick --continue, or similar when nothing is paused; the error text names the operation. |
pathspec_no_match |
grit add, rm, restore, commit -- <paths>, or stash path selection with no matching files. |
stash_not_found |
grit stash pop / apply / drop with an empty stash or an invalid index (hint for empty stash). |
path_not_found |
grit blame (or similar) when the path is absent from the named revision and not on disk. |
gitbutler_workspace |
grit commit while HEAD is on a GitButler workspace (gitbutler/workspace, topped by GitButler's workspace commit). GitButler rewrites that branch, so a commit there would be lost. Hint: commit with but commit, or switch to a branch first. |
unsupported_object_store |
The operation needs the files-backed object store (loose objects and packs under objects/), but the repository's primary store is custom (exit 1). operation is the refused operation's stable name, such as prune (a custom store that cannot delete objects), repack, commit_graph_write or partial_fetch; the object stores guide lists every name. grit itself always opens the files backend, so this comes from repositories opened through grit-lib with a custom store. |