# Exit codes

> Process exit status for grit commands and structured JSON error kinds.

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](https://grit-scm.com/docs/scripting/index.md) and the [Agent guide](https://grit-scm.com/docs/agents/index.md) 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`](https://grit-scm.com/docs/push/index.md) or [`grit sync`](https://grit-scm.com/docs/sync/index.md) did its work, but another member's head of a [shared branch](https://grit-scm.com/docs/share/index.md) 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](https://grit-scm.com/docs/exit-codes/schemas/error/v1.json/index.md)). 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`).

```console
$ 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](https://grit-scm.com/docs/exit-codes/schemas/error/v1.json/index.md) 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](https://grit-scm.com/docs/library/object-stores/index.md#what-works-with-a-custom-primary) lists every name. `grit` itself always opens the files backend, so this comes from repositories opened through `grit-lib` with a custom store. |
