TraceHell shows where Rust's ? operator returns an error.
It creates an instrumented copy of a Rust workspace and reports the exact question-mark expression that passes an error back to its caller. The original source stays untouched.
Rust's ? operator keeps error-handling code concise, but a chain of propagated
errors can make the first failing expression harder to spot. TraceHell rewrites
those expressions in a separate copy of the workspace so each propagated error
prints useful context.
Example output:
? src/parse.rs:42: file.read_to_string(&mut contents) -> Os { code: 2, kind: NotFound, ... }
TraceHell requires Rust with Cargo and one supported terminal: Kitty, Alacritty, or GNOME Terminal.
# Install from a local checkoutcargo install --path .
# From the Rust project you want to inspectcargo tracehell create my-trace
# Run a command inside the instrumented copycargo tracehell run my-trace cargo runOn first use, TraceHell asks which terminal to launch and stores the choice in
~/TraceHall_settings. Instrumented copies live under ~/.TraceHell.
| Command | Purpose |
|---|---|
create <name> | Copies the current Cargo workspace and instruments its Rust source files. |
run <name> <command> | Opens the named copy in the configured terminal and runs the supplied command. |
delete <name> | Removes the named copy from ~/.TraceHell. |
help | Prints usage, available commands, examples, and the installed version. The aliases -help, --help, and -h are also accepted. |
Every command accepts a bare name, a single dash, or a double dash. For example:
cargo tracehell create parser-debugcargo tracehell --run parser-debug cargo testcargo tracehell -delete parser-debugcargo tracehell help- Clone the workspace. Project files are copied into a named directory
under
~/.TraceHell. Build output and Git metadata are skipped. - Rewrite try expressions. Rust files are parsed with
syn. Each?expression becomes a match that prints context before returning an error. - Launch the trace. The selected terminal opens in the copied workspace and runs the supplied command, leaving the shell open afterward.
When an instrumented expression returns Err, TraceHell writes the following
context to standard error:
- The path produced by Rust's
file!()macro - The line number of the generated trace point
- A colored
?marker - The expression as source text
- The error's debug representation
Trace names must be a single path component. Before launching a command, the
current command filter rejects text containing rm, dd, wipefs, or sudo.
cargo buildcargo testcargo fmt --checkTraceHell is written in Rust 2024 and distributed under the Apache License 2.0.