gix-error / Exn Migration Plan

Source issue: GitoxideLabs/gitoxide#2351
Imported on: 2026-04-22
Working assumption: the checkboxes in this file reflect the current gix-error branch in this checkout, not only the historical state of the upstream issue.

Mission

Finish the migration from thiserror-based error enums to gix-error / Exn, while preserving three caller-facing properties:

• typed validation failures stay identifiable as gix_error::ValidationError
• repository-open failures keep a distinct NotARepository path
• crate-local plumbing errors stay cheap and composable until they are intentionally erased at the gix boundary

Constraints

• Use the current workspace as the source of truth for completion.
• Treat upstream PR history as context only. Several linked PRs are merged upstream, but that work is not fully reflected in this branch.
• Keep migration leaf-first so downstream breakage stays local.

Reconciled Status

• Proof of concept completed in #2352, merged on January 12, 2026.
• anyhow / source-chain integration completed in #2383, merged on January 19, 2026.
• Make cargo nextest --workflow run without --exclude gix-error. Evidence: .github/workflows/ci.yml still excludes gix-error.
• Replace thiserror with gix-error everywhere. Evidence: 33 crates in this branch still carry a thiserror dependency and/or thiserror::Error usage.
• Keep NotARepository distinct from generic open failures. Evidence: gix::open::Error::NotARepository exists and is asserted in tests.
• Use gix_error::Error in tests when that simplifies Exn-heavy paths. Evidence: partially adopted, but not clearly finished as a repo-wide sweep.
• Make gix-validate failures identifiable as gix_error::ValidationError. Evidence: gix-error exports ValidationError, and downstream crates already use it directly.

Current Snapshot

Workspace scan basis:

• thiserror dependency present in Cargo.toml
• thiserror::Error mentions under src/**/*.rs

Result on 2026-04-22:

• 32 crates are done
• 33 crates are still pending

Linked Upstream PRs

• #2352 gix-error punch-through
• #2373 Convert more crates to gix-error
• #2378 gix-commitgraph to gix-error
• #2383 anyhow integration for gix-error
• #2389 custom error implementation follow-up
• #2390 make validate errors non-exhaustive
• #2396 gix-actor
• #2400 more gix-error
• #2423 batch 1, part 1

Migration Rules

• Replace thiserror in Cargo.toml with gix-error.
• Prefer pub type Error = gix_error::Exn<gix_error::Message>; unless the crate needs a more specific concrete error.
• Convert validation/parsing-only paths to gix_error::ValidationError.
• Replace #[from] / #[source] propagation with .or_raise(...) or .ok_or_raise(...).
• Keep gix_error::Error as the erased boundary type, mainly at gix and in tests that benefit from downcasting or frame inspection.
• When migrating a crate, run its local checks and at least one downstream compile pass.

Execution Order

Batch 1: leaves

• gix-hash - 7
• gix-url - 3
• gix-packetline - 3
• gix-features - 3
• gix-path - 2
• gix-attributes - 2
• gix-quote
• gix-lock - 1
• gix-fs
• gix-bitmap
• gix-mailmap

Batch 2: simple dependents

• gix-object - 11
• gix-config-value - 2
• gix-shallow - 2
• gix-refspec - 1

Batch 3: ref / filter layer

• gix-ref - 22
• gix-filter - 18
• gix-revwalk - 4
• gix-pathspec - 3
• gix-prompt - 1

Batch 4: config and discovery

• gix-traverse - 3
• gix-config - 11
• gix-credentials - 5
• gix-discover - 4

Batch 5: transport and index-adjacent

• gix-index - 11
• gix-transport - 10
• gix-worktree-stream
• gix-submodule - 6

Batch 6: diff / protocol tier

• gix-diff - 8
• gix-protocol - 8
• gix-dir - 1
• gix-worktree-state - 1
• gix-archive

Batch 7: heavier consumers

• gix-pack - 23
• gix-merge - 8
• gix-status - 3
• gix-blame - 1

Batch 8: object database

• gix-odb - 11

Batch 9: top-level API

• gix - 138

Already Done Outside The Active Queue

• gix-actor
• gix-chunk
• gix-command
• gix-commitgraph
• gix-date
• gix-error
• gix-fetchhead
• gix-fsck
• gix-glob
• gix-hashtable
• gix-ignore
• gix-lfs
• gix-macros
• gix-negotiate
• gix-note
• gix-rebase
• gix-revision
• gix-sec
• gix-sequencer
• gix-tempfile
• gix-tix
• gix-trace
• gix-tui
• gix-utils
• gix-validate
• gix-worktree

Immediate Next Moves

• Finish Batch 1 in this branch before assuming the upstream batch-1 PR history is present locally.
• Remove the gix-error special-case from .github/workflows/ci.yml.
• Re-scan counts after each crate or mini-batch instead of trusting the original issue numbers.
• Only move gix itself after all plumbing crates beneath it are clean.

Exit Criteria

• No crate in this workspace depends on thiserror.
• No src/**/*.rs file in this workspace mentions thiserror::Error.
• cargo nextest --workflow no longer excludes gix-error.
• The gix boundary still returns gix_error::Error where type erasure is desired.
• Validation-heavy crates still expose typed validation failures where callers need them.