# errors

# Typed errors in grit-lib

Grit-lib returns **structured errors**, not strings. Every fallible library call returns [`grit_lib::error::Result`](https://docs.rs/grit-lib/latest/grit_lib/error/type.Result.html), whose error is the umbrella [`Error`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html). The umbrella has **one variant per functional area**, and each area variant carries that area's own `#[non_exhaustive]` `thiserror` enum (see the [error contract](https://github.com/gitbutlerapp/grit/blob/main/grit-lib/API.md#4-typed-errors-per-area) in `API.md`).

## Matching an error

Match the area first, then the area's variant:

```rust
use grit_lib::error::{Error, RefError, RevisionError};

fn describe(err: &Error) -> &'static str {
    match err {
        Error::Revision(RevisionError::NotFound { .. }) => "no such revision",
        Error::Ref(RefError::UnbornHead) => "no commits yet",
        Error::LockHeld(_) => "another process holds a lock",
        err if err.is_cancelled() => "cancelled",
        _ => "something else",
    }
}
```

Both [`Error`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html) and every area enum are `#[non_exhaustive]`, so a match always ends in a wildcard arm. Area enums convert into the umbrella with `From`, so `?` works across areas inside your own code.

## Rules

- Match on **types and variants**, not message text. Human wording is for the CLI only.
- No catch-all `Message(String)` variant anywhere; no `Result<_, String>` in the public API.
- Named fields only: `PathBuf`, object ids, ref names, reason enums. A bare `String` field is allowed only for **external data** (for example a remote's error line) and must be a **named** field, not a tuple variant.
- Use [`PathIoError`](https://docs.rs/grit-lib/latest/grit_lib/error/struct.PathIoError.html) for path-related I/O; do not add bare `#[from] io::Error` on area enums.
- Area enums never hold another umbrella `Error`. A failure in a lower area surfaces as that area's own umbrella variant (a missing object during a checkout is [`Error::Object`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Object), not a checkout error that wraps it).
- When a variant must report a *secondary* failure next to its own (a rollback that also failed, one promisor remote's failure among several), it keeps an [`ErrorSummary`](https://docs.rs/grit-lib/latest/grit_lib/error/struct.ErrorSummary.html) of it: the inner failure's `kind`, `area`, message and whether it was a cancellation.
- Corrupt loose/packed reads use [`ObjectReadFailure`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.ObjectReadFailure.html) as the `source` of [`ObjectError::CorruptLoose`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.ObjectError.html#variant.CorruptLoose) / [`ObjectError::CorruptPacked`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.ObjectError.html#variant.CorruptPacked).
- Public functions return `grit_lib::error::Result<T>` (or a small leaf error for pure parsers), not per-area type aliases.

## Shared leaf types

| Type | Role |
| --- | --- |
| [`LockHeldError`](https://docs.rs/grit-lib/latest/grit_lib/error/struct.LockHeldError.html) | Lock file exists; optional [`LockHolder`](https://docs.rs/grit-lib/latest/grit_lib/lockfile/struct.LockHolder.html) from the pid sidecar ([`Error::LockHeld`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.LockHeld)) |
| [`PathIoError`](https://docs.rs/grit-lib/latest/grit_lib/error/struct.PathIoError.html) | Worktree or git-dir path I/O with [`PathIoOperation`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.PathIoOperation.html); read it back with [`Error::path_io`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#method.path_io) |
| [`Cancelled`](https://docs.rs/grit-lib/latest/grit_lib/error/struct.Cancelled.html) | Operation stopped via [`CancelToken`](https://docs.rs/grit-lib/latest/grit_lib/progress/struct.CancelToken.html) ([`Error::Cancelled`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Cancelled); test with [`Error::is_cancelled`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#method.is_cancelled)) |
| [`ErrorSummary`](https://docs.rs/grit-lib/latest/grit_lib/error/struct.ErrorSummary.html) | Kind, area and message of a secondary failure inside another error |
| [`ObjectReadFailure`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.ObjectReadFailure.html) | Non-recursive decode failure for corrupt loose/packed object reads |

## Area map

| Umbrella variant | Area enum | Covers |
| --- | --- | --- |
| [`Error::Repository`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Repository) | [`RepositoryError`](https://docs.rs/grit-lib/latest/grit_lib/repo/error/enum.RepositoryError.html) | open, init, layout, ownership, git-dir path I/O |
| [`Error::Object`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Object) | [`ObjectError`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.ObjectError.html) | object ids, ODB, packs, MIDX, bitmaps, promisor fetches |
| [`Error::Index`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Index) | [`IndexError`](https://docs.rs/grit-lib/latest/grit_lib/index/error/enum.IndexError.html) | corrupt bytes, unmerged paths, fsmonitor/cache-tree extensions, split index |
| [`Error::Ref`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Ref) | [`RefError`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.RefError.html) | ref names, `HEAD` state, ref store, reftable, reflog |
| [`Error::Revision`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Revision) | [`RevisionError`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.RevisionError.html) | rev-parse, rev-list, merge bases |
| [`Error::Config`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Config) | [`ConfigError`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.ConfigError.html) | config parsing, includes, writes |
| [`Error::Worktree`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Worktree) | [`WorktreeError`](https://docs.rs/grit-lib/latest/grit_lib/worktree/enum.WorktreeError.html) | checkout, status, add/rm/mv/restore/clean, pathspec, filters, submodules, linked worktrees |
| [`Error::Diff`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Diff) | [`DiffError`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.DiffError.html) | diff, blame, apply, hunk selection, textconv |
| [`Error::Commit`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Commit) | [`CommitError`](https://docs.rs/grit-lib/latest/grit_lib/porcelain/enum.CommitError.html) | messages, identity, signing, change ids |
| [`Error::Merge`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Merge) | [`MergeError`](https://docs.rs/grit-lib/latest/grit_lib/porcelain/enum.MergeError.html) | merge, pick, revert, sequencer, operation state, pull |
| [`Error::History`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.History) | [`HistoryError`](https://docs.rs/grit-lib/latest/grit_lib/revwalk/history/enum.HistoryError.html) | history rewrites, rebase sessions, undo |
| [`Error::Stash`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Stash) | [`StashError`](https://docs.rs/grit-lib/latest/grit_lib/stash/enum.StashError.html) | stash push, apply, drop |
| [`Error::Branch`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Branch) | [`BranchError`](https://docs.rs/grit-lib/latest/grit_lib/porcelain/branch/enum.BranchError.html) | branch create, delete, rename, switch targets |
| [`Error::Tag`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Tag) | [`TagError`](https://docs.rs/grit-lib/latest/grit_lib/porcelain/tag/enum.TagError.html) | tag create, delete, verify |
| [`Error::Notes`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Notes) | [`NotesError`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.NotesError.html) | notes refs and edits |
| [`Error::Remote`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Remote) | [`RemoteError`](https://docs.rs/grit-lib/latest/grit_lib/remote/enum.RemoteError.html) | transports, fetch, push, clone, bundles, credentials, serve, snapshot checkouts |
| [`Error::Hook`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Hook) | [`HookError`](https://docs.rs/grit-lib/latest/grit_lib/command_runner/hooks/enum.HookError.html) | hooks that fail or cannot start |
| [`Error::Io`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Io) | `std::io::Error` | I/O not tied to a repository path |
| [`Error::LockHeld`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.LockHeld) | [`LockHeldError`](https://docs.rs/grit-lib/latest/grit_lib/error/struct.LockHeldError.html) | lock contention in any area |
| [`Error::Cancelled`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#variant.Cancelled) | — | cancellation in any area |

Fold tiny areas into a neighbour; do not add an umbrella variant for only one or two failures.

## JSON and scripts

[`Error::kind_name`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#method.kind_name) returns a stable snake_case slug for the specific failure (for example `revision_not_found` or `unborn_head`); each area enum keeps the slugs its variants had before the umbrella collapsed. [`Error::area`](https://docs.rs/grit-lib/latest/grit_lib/error/enum.Error.html#method.area) returns the area (`"revision"`, `"ref"`, …). With the `serde-models` feature a serialized error carries both, as `kind` and the additive `area` field. See [Embedding — Typed errors](https://grit-scm.com/docs/library/errors/docs/library/embedding/index.md#typed-errors).

## Ratchet

Quality counts in [`api-ratchet.toml`](https://github.com/gitbutlerapp/grit/blob/main/grit-lib/api-ratchet.toml) track the umbrella variant count, catch-all variants, string tuples, missing `#[non_exhaustive]`, area enums that hold an umbrella `Error`, and `Error::Message(` construction sites under `grit-lib/src`. The catch-all, string, `non_exhaustive`, nesting and construction-site counts are all zero; `make api-ratchet-check` in CI keeps them there.
