GitoxideLabs/gitoxide gix-error-v0.5.0

gix-error v0.5.0

on GitHub

New Features

• make caller-location printing opt-in

  auto-chain-error also printed source locations in user-facing reports,
  including consumers which only wanted a standard error chain. Make printing
  independently configurable with error-print-location, forwarded by gix.
  The feature gates the shared location writer; caller locations, metadata,
  classification, and the existing alternate-format rules remain intact.

  Enable printing explicitly in workspace binary dependencies and the filter
  test-helper feature. gix-error opts in for its own tests so existing location
  snapshots retain their coverage. An isolated Cargo consumer checks real
  main() stderr for both crates, printing on and off, tree and chain modes,
  and tree-error precedence without workspace test feature unification.

Bug Fixes

• shorten caller locations to package source paths

  Reviewed and refactored carefully, tried the release script as well.
  Didn't review the release script at all though, just had some docs added.
  I consider it disposable.

  Enabled location diagnostics could expose entire checkout and Cargo registry
  paths, obscuring the useful source location with machine-specific directories.
  Format conventional source paths relative to their containing package directory
  and remove Cargo registry version suffixes, so a path such as
  /home/user/.cargo/registry/src/index.crates.io-hash/gix-url-0.39.0/src/parse.rs
  prints as gix-url/src/parse.rs. Unrecognized layouts fall back to the filename.

  Keep captured std::panic::Location values and line numbers intact. The shared
  formatter covers tree, chain, source, test, and main() diagnostics; feature
  defaults and alternate formatting remain unchanged. Document the limitation
  that locations contain no Cargo package metadata and build owners can use
  --remap-path-prefix for exact package names in arbitrary layouts.

• preserve explicit causes in standard error source chains

  Returning a child frame's bare diagnostic from Error::source() lost any
  explicit causes attached to that frame. Standard error reporters, including
  anyhow, could truncate nested context chains before reaching the underlying
  error.

  Keep nonleaf frames reachable as source boundaries while exposing raw leaf
  diagnostics for downcasting. Format each boundary as a single diagnostic to
  avoid duplicating subtrees in external reports, and preserve native-source
  precedence without another allocation.

  Add regression coverage for standard and anyhow traversal and rendering,
  erasure and boxing round trips, and preservation of typed diagnostics,
  classification, and metadata. Document linear source traversal and the
  full-tree inspection alternatives.

• flatten native error chains in linear time

  Exn::into_chain() resolved each native source from its owning root both
  to check for nested boundaries and to construct the next handle. Flattening
  64 errors therefore required 4,096 source() calls.

  Scan each native chain once when constructing its ErrorHandle, recording
  its length and the prefix that inherits the frame location. Advancing a
  handle only increments its depth. Stop at nested Error boundaries to
  preserve breadth-first order, concrete error types, and caller locations
  without extra allocations or dependencies.

  Add native_source_flattening_is_linear to require at most four source
  lookups per error and separately verify that every error survives.
  Chains of 16, 32, and 64 errors now need 16, 32, and 64 source calls.
  Explicit into_chain() calls exercise flattening in every feature
  configuration. Individual handle lookups continue to walk from their owner.

Changed (BREAKING)

• wrap Metadata and simplify diagnostic keys

  Quoting every metadata key adds noise to diagnostic output even when the
  name is already unambiguous. Keep nonempty keys containing only ASCII
  letters, digits, _, -, or . unquoted in Message display and metadata
  debug output. Empty and unusual keys remain quoted and escaped, and value
  formatting is unchanged.

  Replace the public BTreeMap alias with a private-storage Metadata
  wrapper so dictionary formatting and its public API no longer expose the
  implementation. Preserve lexicographic ordering and provide construction,
  lookup, mutation, iteration, indexing, collection, and extension APIs.

  Breaking change: Metadata is no longer interchangeable with
  BTreeMap. Callers must use the wrapper API; iterator return types hide
  the underlying collection.

  Add regression coverage for key quoting, compact values, and dictionary
  access, and update dependent assertions and output snapshots.

• unify workspace diagnostics and error recovery

  Looked at gix-error carefully and did multiple cleanup and improvement passes.
  At some point I went quicker through the changes as they looked good enough,
  also to at some point just wave it through.

  General changes

  Use the workspace's own error API throughout applications, examples, internal
  utilities, and fuzz targets. Replace downstream anyhow::Result, Context,
  bail!, and ensure! usage with gix::Result and helpers from gix::error,
  or gix_error in plumbing crates. Convert native errors at their call sites
  while preserving concrete causes, typed recovery contracts, and caller locations.
  Keep optional anyhow interoperability in gix-error and gix for consumers.

  Make diagnostics useful both to people and to callers deciding how to recover.
  Distinguish invalid input, corrupt data, missing resources, unavailable
  capabilities, authentication, authorization, conflicting state, and cancellation.
  Explicit cancellation prevents retrying even when another cause is retryable.
  Store offending input and available subprocess details as structured metadata,
  with operation context in the message and native failures retained as causes.

  Report causes under a numbered Caused by: section, retaining branch guides for
  error trees and flattening linear chains. Standardize path quoting, refresh
  snapshots, and omit changing source locations from CLI error comparisons.
  Migrate affected tests and helpers to TestResult where they need to propagate
  both native errors and exceptions. Update contributor and application guidance,
  remove redundant dependencies, and refresh the lockfile.

  gix-error: recovery classes, metadata, and complete native reports

  Add Cancelled, PermissionDenied, Unauthenticated, Conflict, and
  Unsupported classes with matching constructors, markers, builders, and
  predicates. Order classes by suggested recovery precedence and expose
  dominant_class(). Both retry policies inspect cancellation across causes;
  native permission and unsupported I/O errors receive classifications, while
  explicit authentication challenges take precedence over legacy permission wrappers.

  Add classified Message builders and _error helpers, caller-tracked
  Message conversions, and formatted bail!/ensure! shorthand with builder
  chains. Introduce with_input(), subprocess metadata helpers, common metadata
  schemas, and metadata_merged(), with more specific causes overriding context.

  Number tree reports while preserving forks and flattening chains. Give
  auto-chain-error complete Debug reports with locations and single-line
  alternate Display chains; share that formatter with TestError. Cover nested
  native sources, classification precedence, metadata, caller tracking, macro
  evaluation, report layout, and retained anyhow interoperability.

  gix: consistent porcelain diagnostics and application guidance

  Document gix::Result, gix::Error, and gix::error for applications. Apply
  classification and input metadata to configuration, initialization, repository
  opening, clone and remote setup, object access, and path handling. Distinguish
  unsupported formats from malformed values, and classify branch/worktree state
  conflicts and explicit cancellation without replacing concrete recovery errors.

  Record signing and key-command failures through subprocess metadata. Migrate
  examples and tests away from anyhow, refresh diagnostics and classification
  assertions, remove the test dependency, and update prodash to 31.0.1.

  gitoxide: native CLI errors and dependency cleanup

  Return gix::Result from gix, ein, the combined binary, and shared command,
  progress, and tracing helpers. Preserve context when configuring repositories,
  writing output, and starting tracing; classify unavailable tracing as unsupported.
  Migrate top-level examples and journey snapshots to native diagnostics.
  Replace is-terminal with std::io::IsTerminal, remove anyhow, and update
  prodash to 31.0.1 with corresponding feature and lockfile cleanup.

• return public errors from extension helpers

  gix-error was refackiewed, the rest was scrolled through to peek out problems
  at best.
  Looked at gix in detail, refackiew, and came up with API improvement to
  gix-config-value on the way.

  Public plumbing APIs now use gix_error::Result, so constructing typed
  exceptions by default requires repeated erasure, conversion, and propagation
  wrappers at their call sites.

  Make raise() and and_raise() return Error, and make or_raise() and
  ok_or_raise() return Result. Preserve the former behavior under explicit
  _typed names and add ResultExt::or_error() for conversion without context.
  Existing public errors pass through unchanged without allocating, while
  context retains concrete causes, metadata, classifications, and caller sites.
  Keep the erased helpers and inherent Exn operations unchanged.

  Migrate callers and documentation together, preserving concrete public
  exception signatures and typed internal boundaries. Use the existing bail!
  macro for 388 early error returns across 37 crates, passing native errors and
  messages directly and retaining context and explicit erasure on typed
  exceptions. Preserve direct propagation of public Error values to avoid
  introducing extra exception frames.

• standardize public errors and reuse exception frames

  rubber-stamp after scrolling through the diff top to bottom.
  gix-error changes were refackiewed carefully.

  Use gix_error::Result and gix_error::Error at public plumbing boundaries
  with erased or message-based exceptions so applications can use ordinary
  std::error::Error handling while retaining concrete recovery errors,
  causes, metadata, and caller locations. Apply this to public traits,
  callbacks, iterator items, and re-exported APIs, and adapt their consumers
  throughout the workspace. Preserve concrete public error signatures and
  typed internal exceptions; let bail! convert to either result form.

  Add Error::into_exn() for internal tree manipulation, including the
  revision parser's delayed errors. Recover explicitly raised frames in
  auto-chain-error mode and forward native source chains through nested
  Error wrappers. Reuse existing boxed tree frames when adding context or
  erasing errors to avoid redundant boxing, and keep context construction
  independent of existing chain depth.

  Remove repeated propagation wrappers from callers and update the migration
  guide and repository conventions. Document the value of context that
  explains an operation's intent or identifies user-controlled configuration,
  including its raise location, even when failures are rare.

  Remove Class::Io and the synthetic io() constructor so classifications
  describe semantic failures. Retain NotFound and OutOfMemory
  classifications for real I/O errors, and inspect their concrete causes for
  the conservative and lenient retry policies.

• replace recovery tags with typed operation errors

  GitButler needs to distinguish missing binary merge results, ambiguous object
  prefixes, diff setup failures, unrelated histories, and repository discovery
  outcomes. Broad classifications alone also match failures that these callers
  must propagate, such as missing-directory I/O and rejected repository trust.

  Remove Class::Tagged and expose non-exhaustive Error enums for these
  operations. Share the merge-base enum across pair, many, and octopus methods,
  and keep porcelain returns as gix::Result. Preserve candidate information,
  native paths, diff resource details, requested commit IDs, and callee causes.

  Add gix_error::tag() and make classifications identify the wrapped error or
  the owner of a constant marker source. Keep traversal lazy and preserve its
  order, duplicates, marker transparency, and original I/O kinds in both error
  representations. Document typed recovery and wildcard propagation.

  Validate merge-base input commits in the shared traversal path so missing
  inputs cannot masquerade as unrelated histories, including fast paths and
  octopus calls. Continue allowing absent parents for shallow histories and
  empty successful results for merge_bases_many*() on unrelated histories.

  Fix the recovery tests failing in Linux/ARM test-fast and Windows
  test-fixtures-windows CI. Discovery examines the ceiling directory before
  stopping, so its immediate child reports a stopping height of 2. Attribute
  lookup converts Git paths to native paths, rejecting ill-formed UTF-8 on
  Windows before reaching object lookup. Cover missing-object conversion with
  a valid path everywhere and retain its non-UTF-8 path case on Unix.

New Features (BREAKING)

• make bstr an opt-in metadata conversion feature

  Small error-handling programs should not compile bstr and memchr just
  to add ordinary error contexts. Disable bstr by default so a standalone
  gix-error consumer needs no dependencies unless it enables optional features.

  Always store MetadataValue::Bytes as Vec<u8>, regardless of features.
  This changes the public variant payload from BString. Keep escaped debug
  and display diagnostics compatible with bstr, including valid Unicode,
  control characters, invalid bytes, and truncated UTF-8.

  The opt-in bstr feature supplies From<BString> and From<&BStr> for
  MetadataValue and retains the crate re-export. Owned conversions reuse
  the allocation; borrowed conversions copy the bytes. Enable the feature
  explicitly in workspace crates that need these conversions or the re-export,
  preserving their with_input() and with() calls. Adapt direct byte
  constructors and submodule payload access to the new Vec<u8> representation.

  Earlier five-sample fresh-build measurements of the same small consumer on
  Rust 1.99.0 / M4 Max recorded medians of 702 vs 458 ms in debug and 872 vs
  609 ms in release with and without bstr. These include Cargo and linking
  with registry sources cached; they are specific to that consumer and machine.

Commit Statistics

• 16 commits contributed to the release over the course of 13 calendar days.
• 13 days passed between releases.
• 10 commits were understood as conventional.
• 0 issues like '(#ID)' were seen in commit messages

Commit Details