grit
CLILibrary
HEAD → docs/library/errors
Library guide / errorsMarkdown

errors

Typed errors in grit-lib

Grit-lib returns structured errors, not strings. Every fallible library call returns grit_lib::error::Result, whose error is the umbrella Error. 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 in API.md).

Matching an error

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

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 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 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, 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 of it: the inner failure's kind, area, message and whether it was a cancellation.
  • Corrupt loose/packed reads use ObjectReadFailure as the source of ObjectError::CorruptLoose / ObjectError::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 Lock file exists; optional LockHolder from the pid sidecar (Error::LockHeld)
PathIoError Worktree or git-dir path I/O with PathIoOperation; read it back with Error::path_io
Cancelled Operation stopped via CancelToken (Error::Cancelled; test with Error::is_cancelled)
ErrorSummary Kind, area and message of a secondary failure inside another error
ObjectReadFailure Non-recursive decode failure for corrupt loose/packed object reads

Area map

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

Ratchet

Quality counts in 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.