Merge pull request GitoxideLabs#2400 from GitoxideLabs/gix-error

More of `gix-error`

Author: Byron

.claude/instructions.md

@@ -0,0 +1,13 @@
+# Claude Code Instructions for Gitoxide
+
+See [.github/copilot-instructions.md](../.github/copilot-instructions.md) for project conventions,
+architecture decisions, error handling patterns, and development practices.
+
+## Quick Reference
+
+- `cargo test -p <crate-name>` to test a specific crate
+- `cargo check -p gix` to check the main crate with default features
+- `just check` to build all code in suitable configurations
+- `just test` to run all tests, clippy, and journey tests
+- `cargo fmt` to format all code
+- `cargo clippy --workspace --all-targets -- -D warnings -A unknown-lints --no-deps` to lint all code

.github/copilot-instructions.md

@@ -5,27 +5,53 @@ This repository contains `gitoxide` - a pure Rust implementation of Git. This do
 ## Project Overview
 
 - **Language**: Rust (MSRV documented in gix/Cargo.toml)
-- **Structure**: Cargo workspace with multiple crates (gix-*, gitoxide-core, etc.)
+- **Structure**: Cargo workspace with multiple crates (gix-\*, gitoxide-core, etc.)
 - **Main crates**: `gix` (library entrypoint), `gitoxide` binary (CLI tools: `gix` and `ein`)
 - **Purpose**: Provide a high-performance, safe Git implementation with both library and CLI interfaces
 
 ## Development Practices
 
 ### Test-First Development
+
 - Protect against regression and make implementing features easy
 - Keep it practical - the Rust compiler handles mundane things
 - Use git itself as reference implementation; run same tests against git where feasible
 - Never use `.unwrap()` in production code, avoid it in tests in favor of `.expect()` or `?`. Use `gix_testtools::Result` most of the time.
 - Use `.expect("why")` with context explaining why expectations should hold, but only if it's relevant to the test.
 
 ### Error Handling
+
 - Handle all errors, never `unwrap()`
 - Provide error chains making it easy to understand what went wrong
-- Use `thiserror` for libraries generally
 - Binaries may use `anyhow::Error` exhaustively (user-facing errors)
 
+#### `gix-error` (preferred for plumbing crates)
+
+Plumbing crates are migrating from `thiserror` enums to `gix-error`. Check whether a crate already
+uses `gix-error` (look at its `Cargo.toml`); if it does, follow the patterns below. If it still uses
+`thiserror`, keep using `thiserror` for consistency within that crate.
+
+- **Error type alias**: `pub type Error = gix_error::Exn<gix_error::Message>;`
+- **Static messages**: `gix_error::message("something failed")`
+- **Formatted messages**: `gix_error::message!("failed to read {path}")`
+- **Wrapping callee errors with context**: `.or_raise(|| message("context about what failed"))?`
+- **Standalone error (no callee)**: `Err(message("something went wrong").raise())`
+- **Wrapping an `impl Error` with context**: `err.and_raise(message("context"))`
+- **Closure/callback bounds**: use `Result<T, Exn>` (bare), not `Exn<Message>`;
+  inside the function, convert with `.or_raise(|| message("..."))?`;
+  inside the closure, convert typed to bare with `.or_erased()`
+- **`Exn<E>` does NOT implement `std::error::Error`** — this is by design.
+  - To convert: use `.into_error()` to get `gix_error::Error` (which does implement `std::error::Error`)
+  - Example: `std::io::Error::other(exn.into_error())`
+- **In tests** returning `gix_testtools::Result` (= `Result<(), Box<dyn Error>>`), `Exn` can't be used
+  with `?` directly — use `.map_err(|e| e.into_error())?`
+- **Common imports**: `use gix_error::{message, ErrorExt, ResultExt};`
+- See `gix-error/src/lib.rs` module docs for a full migration guide from `thiserror`
+
 ### Commit Messages
+
 Follow "purposeful conventional commits" style:
+
 - Use conventional commit prefixes ONLY if message should appear in changelog
 - Breaking changes MUST use suffix `!`: `change!:`, `remove!:`, `rename!:`
 - Features/fixes visible to users: `feat:`, `fix:`
@@ -36,67 +62,78 @@ Follow "purposeful conventional commits" style:
   - `change!: rename Foo to Bar. (#123)`
 
 ### Code Style
+
 - Follow existing patterns in the codebase
 - No `.unwrap()` - use `.expect("context")` if you are sure this can't fail.
 - Prefer references in plumbing crates to avoid expensive clones
 - Use `gix_features::threading::*` for interior mutability primitives
 
 ### Path Handling
+
 - Paths are byte-oriented in git (even on Windows via MSYS2 abstraction)
 - Use `gix::path::*` utilities to convert git paths (`BString`) to `OsStr`/`Path` or use custom types
 
 ## Building and Testing
 
 ### Quick Commands
+
 - `just test` - Run all tests, clippy, journey tests, and try building docs
 - `just check` - Build all code in suitable configurations
 - `just clippy` - Run clippy on all crates
 - `cargo test` - Run unit tests only
 
 ### Build Variants
+
 - `cargo build --release` - Default build (big but pretty, ~2.5min)
 - `cargo build --release --no-default-features --features lean` - Lean build (~1.5min)
 - `cargo build --release --no-default-features --features small` - Minimal deps (~46s)
 
 ### Test Best Practices
+
 - Run tests before making changes to understand existing issues
 - Use `GIX_TEST_IGNORE_ARCHIVES=1` when testing on macOS/Windows
 - Journey tests validate CLI behavior end-to-end
 
 ## Architecture Decisions
 
 ### Plumbing vs Porcelain
+
 - **Plumbing crates**: Low-level, take references, expose mutable parts as arguments
 - **Porcelain (gix)**: High-level, convenient, may clone Repository for user convenience
 - Platforms: cheap to create, keep reference to Repository
 - Caches: more expensive, clone `Repository` or free of lifetimes
 
 ### Options vs Context
+
 - Use `Options` for branching behavior configuration (can be defaulted)
 - Use `Context` for data required for operation (cannot be defaulted)
 
 ## Crate Organization
 
 ### Common Crates
+
 - `gix`: Main library entrypoint (porcelain)
 - `gix-object`, `gix-ref`, `gix-config`: Core git data structures
 - `gix-odb`, `gix-pack`: Object database and pack handling
 - `gix-diff`, `gix-merge`, `gix-status`: Operations
 - `gitoxide-core`: Shared CLI functionality
 
 ## Documentation
+
 - High-level docs: README.md, CONTRIBUTING.md, DEVELOPMENT.md
 - Crate status: crate-status.md
 - Stability guide: STABILITY.md
 - Always update docs if directly related to code changes
 
 ## CI and Releases
+
 - Ubuntu-latest git version is the compatibility target
 - `cargo smart-release` for releases (driven by commit messages)
 - Split breaking changes into separate commits per affected crate if one commit-message wouldn't be suitable for all changed crates.
 - First commit: breaking change only; second commit: adaptations
 
 ## When Suggesting Changes
+
 1. Understand the plumbing vs porcelain distinction
 2. Check existing patterns in similar crates
 3. Follow error handling conventions strictly

Cargo.lock

@@ -35,7 +35,7 @@ gix-date = { version = "^0.13.0", path = "../gix-date" }
 flate2 = { version = "1.1.8", optional = true, default-features = false, features = ["zlib-rs"] }
 rawzip = { version = "0.4.3", optional = true }
 
-thiserror = "2.0.18"
+gix-error = { version = "^0.0.0", path = "../gix-error" }
 bstr = { version = "1.12.0", default-features = false }
 
 tar = { version = "0.4.38", optional = true }

gix-archive/Cargo.toml

@@ -19,22 +19,7 @@
 use bstr::BString;
 
 /// The error returned by [`write_stream()`].
-#[derive(Debug, thiserror::Error)]
-#[allow(missing_docs)]
-pub enum Error {
-    #[error(transparent)]
-    Io(#[from] std::io::Error),
-    #[error(transparent)]
-    NextStreamEntry(#[from] gix_worktree_stream::entry::Error),
-    #[error("The internal format cannot be used as an archive, it's merely a debugging tool")]
-    InternalFormatMustNotPersist,
-    #[error("Support for the format '{wanted:?}' was not compiled in")]
-    SupportNotCompiledIn { wanted: Format },
-    #[error("Cannot create a zip archive if output stream does not support seek")]
-    ZipWithoutSeek,
-    #[error("Cannot use modification as it is not within the supported bounds")]
-    InvalidModificationTime(#[source] Box<dyn std::error::Error + Send + Sync + 'static>),
-}
+pub type Error = gix_error::Exn<gix_error::Message>;
 
 /// The supported container formats for use in [`write_stream()`].
 #[derive(Default, PartialEq, Eq, Copy, Clone, Debug)]