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; noResult<_, String>in the public API. - Named fields only:
PathBuf, object ids, ref names, reason enums. A bareStringfield is allowed only for external data (for example a remote's error line) and must be a named field, not a tuple variant. - Use
PathIoErrorfor path-related I/O; do not add bare#[from] io::Erroron 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 isError::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
ErrorSummaryof it: the inner failure'skind,area, message and whether it was a cancellation. - Corrupt loose/packed reads use
ObjectReadFailureas thesourceofObjectError::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.