{"owner":"cachix","repo":"devenv","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\nWhen creating git commits, add entry to CHANGELOG.md (skip for src/modules/* and docs/* and refactorings not affecting behavior):\n\n## Build & Development Commands\n\nUse `devenv shell` to get a shell with Rust and all dependencies installed.\nPrefix commands with `devenv shell --` to run them directly.\n\n- **Build**: `cargo build`\n- **Run CLI**: `cargo run -- [args]`\n- **Build with Nix**: `nix build`\n- **Format**: `cargo fmt`\n- **Lint**: `cargo clippy`\n- **Run all tests**: `devenv-run-tests run tests`\n- **Run single test**: `devenv-run-tests run tests --only <test_name>`\n- **Run unit tests**: `cargo nextest run`\n- **Run unit tests (single crate)**: `cargo nextest run -p <crate_name>`\n- **Run all unit tests (including feature-gated)**: `cargo nextest run --features devenv/test-all`\n\n## Architecture Overview\n\ndevenv is a Rust CLI tool that creates fast, declarative, reproducible developer environments using Nix. The codebase is organized as a Cargo workspace.\n\n### Core Crates\n\n- **devenv/** - Main CLI binary. Entry point is `main.rs` which handles three runtime modes (TUI, legacy CLI, tracing). Command dispatch happens in `devenv.rs`. CLI definitions use clap in `cli.rs`.\n\n- **devenv-core/** - Shared types and abstractions:\n  - `config.rs` - Configuration parsing (`devenv.yaml`, `devenv.local.yaml`)\n  - `evaluator.rs` - The `Evaluator` trait that abstracts Nix evaluation\n  - `store.rs` - The `Store` trait for talking to a Nix store\n  - `backend.rs` - `Backend<E>`, devenv-shaped facade over an `Evaluator`\n  - `paths.rs` - `DevenvPaths` on-disk layout\n\n- **devenv-nix-backend/** - C FFI-based Nix backend using `nix-bindings-*` crates. Provides direct API access to Nix without subprocess spawning. This is the default backend.\n\n- **devenv-snix-backend/** - Experimental pure-Rust Nix evaluator backend using Snix (feature-gated with `snix`).\n\n- **devenv-tasks/** - DAG-based task execution system with caching, parallel execution, and privilege escalation support.\n\n- **devenv-activity/** - Tracing-based activity system that powers the TUI progress display. Use `#[instrument_activity(\"description\")]` macro for TUI-visible operations.\n\n- **devenv-tui/** - Terminal UI for displaying build progress and activities.\n\n- **devenv-eval-cache/** - SQLite-based caching for Nix evaluation results. Tracks file and env dependencies to invalidate cache.\n\n- **devenv-cache-core/** - Shared utilities for file hashing and SQLite operations used by both eval and task caches.\n\n- **devenv-run-tests/** - Test harness for integration tests. Runs tests in isolated temp directories with fresh environments.\n\n- **tokio-shutdown/** - Graceful shutdown manager handling SIGINT/SIGTERM with cleanup coordination.\n\n- **nix-conf-parser/** - Parser for `nix.conf` format (output of `nix config show`).\n\n- **xtask/** - Build automation (manpage and shell completion generation).\n\n### Configuration Flow\n\n1. User creates `devenv.yaml` (inputs) and `devenv.nix` (configuration)\n2. `Config::load()` in devenv-core parses YAML and resolves inputs\n3. `Devenv::assemble()` generates a temporary flake structure in `.devenv/`\n4. `NixBackend` evaluates the flake to produce shell environment or build outputs\n\n### Key Patterns\n\n- **Dual Backend Architecture**: The `NixBackend` trait allows swapping between the FFI-based backend (default) and Snix backend.\n- **Activity Tracing**: Use `#[instrument_activity(\"description\")]` macro or `activity!(INFO, operation, \"...\")` for TUI-visible operations.\n- **Error Handling**: Use `miette` for errors with `bail!()` and `?`. Custom error types use `thiserror`.\n- **SQLite Migrations**: Both `devenv-eval-cache` and `devenv-tasks` use sqlx with migrations in `migrations/` directories.\n\n## Testing\n\nIntegration tests live in `tests/` and `examples/` directories. Each test is a directory containing:\n- `devenv.nix` - The configuration to test\n- `.test.sh` - Test script (runs inside devenv shell by default)\n- `.test-config.yml` (optional) - Test configuration:\n  - `use_shell: false` - Run `.test.sh` directly, not in devenv shell\n  - `git_init: false` - Don't initialize git repo in temp dir\n  - `supported_systems` / `broken_systems` - Platform filtering\n\n### Cargo Feature Flags\n\n- **`devenv/test-all`** — Enables all feature-gated unit tests across the workspace.\n  Propagates to `devenv-processes/test-all`, `devenv-nix-backend/test-all`, `devenv-reload/test-all`, `devenv-shell/test-all`, and `devenv-tui/test-all`.\n- **`devenv/test-mcp`** — Enables MCP-related tests.\n- **`devenv/snix`** — Enables the experimental Snix backend.\n- **`devenv-shell/test-pty`** — Enables PTY-based session tests (requires a real terminal).\n- **`deterministic-tui`** — Available on both `devenv-shell` and `devenv-tui`.\n  Replaces spinner animation and elapsed time formatting with static placeholders (`[TIME]`, fixed spinner frame) so that TUI snapshot tests produce deterministic output.\n  Enabled automatically by `test-all` on both crates.\n\n\n## Tracing / Debugging\n\nTracing is disabled by default.\nEnable it with `--trace-to` using the syntax `[format:]destination`.\nMultiple outputs can be active simultaneously by repeating the flag.\n\n- **Trace to stderr**: `cargo run -- --trace-to stderr shell`\n- **Trace to file**: `cargo run -- --trace-to file:/tmp/devenv.log shell`\n- **Pretty format**: `cargo run -- --trace-to pretty:stderr shell`\n- **JSON format** (default): `cargo run -- --trace-to json:stderr shell`\n- **Full format**: `cargo run -- --trace-to full:stderr shell`\n- **Multiple outputs**: `cargo run -- --trace-to pretty:stderr --trace-to json:file:/tmp/trace.json shell`\n\nWhen format is omitted, defaults to json.\nWhen any output targets stdout or stderr, the TUI is automatically disabled.\n\nEnvironment variable `DEVENV_TRACE_TO` accepts comma-separated specs (e.g. `DEVENV_TRACE_TO=pretty:stderr,json:file:/tmp/t.json`).\n\n### Authoring trace events\n\n`tracing` (`trace!`, `debug!`, `info!`, `warn!`, `error!`) is for **developers** debugging devenv itself — visible via `--trace-to` or `RUST_LOG`.\n**User-facing output is the activity system**, not `tracing`.\nUse `activity!(...)`, `instrument_activity`, or `message(level, \"...\")` to surface anything the user should see in the TUI or non-TUI console.\n\nLevel choice:\n\n- `error!` — operation failed, user needs to know.\n- `warn!` — degraded path that succeeded (fallback used, retry happened).\n- `info!` — major lifecycle events worth noting in a normal run.\n- `debug!` — diagnostics useful when something goes wrong (cache hits/misses, decision points, request boundaries). Enabled by `--verbose`. Cost: small.\n- `trace!` — fine-grained internal flow (per-iteration, per-byte, per-state-transition). Enabled only by explicit `RUST_LOG=trace`. Cost: can be hot.\n\nRule of thumb: if an operator debugging a production issue would want it → `debug!`. If only the library author tracing internal flow would want it → `trace!`.\n\nMessage style: lowercase, no leading capital, no trailing period. Structured fields carry the data. Examples:\n\n```rust\ndebug!(key_hash = %key, \"cache hit\");\ntrace!(error = %e, \"task join error\");\nwarn!(path = %p.display(), \"failed to read file, falling back to default\");\n```\n\n## Code Style\n\n- **Error Handling**: Use `bail!()` not `panic!()`, propagate with `?`\n- **No unsafe**: Don't use `unsafe` code\n\n## Docs\n\nWhen adding documentation in `docs/`, make sure to note the version the change was added in by checking `Cargo.toml`.\n\n    !!! tip \"New in version X.Y.Y\"\n\n## Changelog\n\n\n`CHANGELOG.md` follows this structure:\n\n```\n## <version> (unreleased)\n\n### Bug Fixes\n\n- Fixed <description> ([#<issue>](https://github.com/cachix/devenv/issues/<issue>)).\n\n### Improvements\n\n- <Description of improvement>.\n\n### Breaking Changes\n\n- **<Name>**: <Description>.\n```\n\nWhen updating the changelog:\n1. Use `git log <last-release-commit>..HEAD` to find commits since the last release.\n2. Skip automated commits (e.g. `Auto generate ...`) and test-only commits.\n3. Group entries under **Bug Fixes**, **Improvements**, or **Breaking Changes**.\n4. Link GitHub issues when referenced in commit messages (search for `Fixes`/`Closes`/`#` in commit bodies).\n5. The unreleased section sits above the last release entry.\n6. Write for users, not maintainers: describe the symptom and user-visible outcome. Omit implementation details (internal variable names, struct names, code paths). One or two sentences max.\n\n## Files That Should Not Be Edited\n\n- `docs/reference/options.md` - Auto-generated from Nix module options\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\nWhen creating git commits, add entry to CHANGELOG.md (skip for src/modules/* and docs/* and refactorings not affecting behavior):\n\n## Build & Development Commands\n\nUse `devenv shell` to get a shell with Rust and all dependencies installed.\nPrefix commands with `devenv shell --` to run them directly.\n\n- **Build**: `cargo build`\n- **Run CLI**: `cargo run -- [args]`\n- **Build with Nix**: `nix build`\n- **Format**: `cargo fmt`\n- **Lint**: `cargo clippy`\n- **Run all tests**: `devenv-run-tests run tests`\n- **Run single test**: `devenv-run-tests run tests --only <test_name>`\n- **Run unit tests**: `cargo nextest run`\n- **Run unit tests (single crate)**: `cargo nextest run -p <crate_name>`\n- **Run all unit tests (including feature-gated)**: `cargo nextest run --features devenv/test-all`\n\n## Architecture Overview\n\ndevenv is a Rust CLI tool that creates fast, declarative, reproducible developer environments using Nix. The codebase is organized as a Cargo workspace.\n\n### Core Crates\n\n- **devenv/** - Main CLI binary. Entry point is `main.rs` which handles three runtime modes (TUI, legacy CLI, tracing). Command dispatch happens in `devenv.rs`. CLI definitions use clap in `cli.rs`.\n\n- **devenv-core/** - Shared types and abstractions:\n  - `config.rs` - Configuration parsing (`devenv.yaml`, `devenv.local.yaml`)\n  - `evaluator.rs` - The `Evaluator` trait that abstracts Nix evaluation\n  - `store.rs` - The `Store` trait for talking to a Nix store\n  - `backend.rs` - `Backend<E>`, devenv-shaped facade over an `Evaluator`\n  - `paths.rs` - `DevenvPaths` on-disk layout\n\n- **devenv-nix-backend/** - C FFI-based Nix backend using `nix-bindings-*` crates. Provides direct API access to Nix without subprocess spawning. This is the default backend.\n\n- **devenv-snix-backend/** - Experimental pure-Rust Nix evaluator backend using Snix (feature-gated with `snix`).\n\n- **devenv-tasks/** - DAG-based task execution system with caching, parallel execution, and privilege escalation support.\n\n- **devenv-activity/** - Tracing-based activity system that powers the TUI progress display. Use `#[instrument_activity(\"description\")]` macro for TUI-visible operations.\n\n- **devenv-tui/** - Terminal UI for displaying build progress and activities.\n\n- **devenv-eval-cache/** - SQLite-based caching for Nix evaluation results. Tracks file and env dependencies to invalidate cache.\n\n- **devenv-cache-core/** - Shared utilities for file hashing and SQLite operations used by both eval and task caches.\n\n- **devenv-run-tests/** - Test harness for integration tests. Runs tests in isolated temp directories with fresh environments.\n\n- **tokio-shutdown/** - Graceful shutdown manager handling SIGINT/SIGTERM with cleanup coordination.\n\n- **nix-conf-parser/** - Parser for `nix.conf` format (output of `nix config show`).\n\n- **xtask/** - Build automation (manpage and shell completion generation).\n\n### Configuration Flow\n\n1. User creates `devenv.yaml` (inputs) and `devenv.nix` (configuration)\n2. `Config::load()` in devenv-core parses YAML and resolves inputs\n3. `Devenv::assemble()` generates a temporary flake structure in `.devenv/`\n4. `NixBackend` evaluates the flake to produce shell environment or build outputs\n\n### Key Patterns\n\n- **Dual Backend Architecture**: The `NixBackend` trait allows swapping between the FFI-based backend (default) and Snix backend.\n- **Activity Tracing**: Use `#[instrument_activity(\"description\")]` macro or `activity!(INFO, operation, \"...\")` for TUI-visible operations.\n- **Error Handling**: Use `miette` for errors with `bail!()` and `?`. Custom error types use `thiserror`.\n- **SQLite Migrations**: Both `devenv-eval-cache` and `devenv-tasks` use sqlx with migrations in `migrations/` directories.\n\n## Testing\n\nIntegration tests live in `tests/` and `examples/` directories. Each test is a directory containing:\n- `devenv.nix` - The configuration to test\n- `.test.sh` - Test script (runs inside devenv shell by default)\n- `.test-config.yml` (optional) - Test configuration:\n  - `use_shell: false` - Run `.test.sh` directly, not in devenv shell\n  - `git_init: false` - Don't initialize git repo in temp dir\n  - `supported_systems` / `broken_systems` - Platform filtering\n\n### Cargo Feature Flags\n\n- **`devenv/test-all`** — Enables all feature-gated unit tests across the workspace.\n  Propagates to `devenv-processes/test-all`, `devenv-nix-backend/test-all`, `devenv-reload/test-all`, `devenv-shell/test-all`, and `devenv-tui/test-all`.\n- **`devenv/test-mcp`** — Enables MCP-related tests.\n- **`devenv/snix`** — Enables the experimental Snix backend.\n- **`devenv-shell/test-pty`** — Enables PTY-based session tests (requires a real terminal).\n- **`deterministic-tui`** — Available on both `devenv-shell` and `devenv-tui`.\n  Replaces spinner animation and elapsed time formatting with static placeholders (`[TIME]`, fixed spinner frame) so that TUI snapshot tests produce deterministic output.\n  Enabled automatically by `test-all` on both crates.\n\n\n## Tracing / Debugging\n\nTracing is disabled by default.\nEnable it with `--trace-to` using the syntax `[format:]destination`.\nMultiple outputs can be active simultaneously by repeating the flag.\n\n- **Trace to stderr**: `cargo run -- --trace-to stderr shell`\n- **Trace to file**: `cargo run -- --trace-to file:/tmp/devenv.log shell`\n- **Pretty format**: `cargo run -- --trace-to pretty:stderr shell`\n- **JSON format** (default): `cargo run -- --trace-to json:stderr shell`\n- **Full format**: `cargo run -- --trace-to full:stderr shell`\n- **Multiple outputs**: `cargo run -- --trace-to pretty:stderr --trace-to json:file:/tmp/trace.json shell`\n\nWhen format is omitted, defaults to json.\nWhen any output targets stdout or stderr, the TUI is automatically disabled.\n\nEnvironment variable `DEVENV_TRACE_TO` accepts comma-separated specs (e.g. `DEVENV_TRACE_TO=pretty:stderr,json:file:/tmp/t.json`).\n\n### Authoring trace events\n\n`tracing` (`trace!`, `debug!`, `info!`, `warn!`, `error!`) is for **developers** debugging devenv itself — visible via `--trace-to` or `RUST_LOG`.\n**User-facing output is the activity system**, not `tracing`.\nUse `activity!(...)`, `instrument_activity`, or `message(level, \"...\")` to surface anything the user should see in the TUI or non-TUI console.\n\nLevel choice:\n\n- `error!` — operation failed, user needs to know.\n- `warn!` — degraded path that succeeded (fallback used, retry happened).\n- `info!` — major lifecycle events worth noting in a normal run.\n- `debug!` — diagnostics useful when something goes wrong (cache hits/misses, decision points, request boundaries). Enabled by `--verbose`. Cost: small.\n- `trace!` — fine-grained internal flow (per-iteration, per-byte, per-state-transition). Enabled only by explicit `RUST_LOG=trace`. Cost: can be hot.\n\nRule of thumb: if an operator debugging a production issue would want it → `debug!`. If only the library author tracing internal flow would want it → `trace!`.\n\nMessage style: lowercase, no leading capital, no trailing period. Structured fields carry the data. Examples:\n\n```rust\ndebug!(key_hash = %key, \"cache hit\");\ntrace!(error = %e, \"task join error\");\nwarn!(path = %p.display(), \"failed to read file, falling back to default\");\n```\n\n## Code Style\n\n- **Error Handling**: Use `bail!()` not `panic!()`, propagate with `?`\n- **No unsafe**: Don't use `unsafe` code\n\n## Docs\n\nWhen adding documentation in `docs/`, make sure to note the version the change was added in by checking `Cargo.toml`.\n\n    !!! tip \"New in version X.Y.Y\"\n\n## Changelog\n\n\n`CHANGELOG.md` follows this structure:\n\n```\n## <version> (unreleased)\n\n### Bug Fixes\n\n- Fixed <description> ([#<issue>](https://github.com/cachix/devenv/issues/<issue>)).\n\n### Improvements\n\n- <Description of improvement>.\n\n### Breaking Changes\n\n- **<Name>**: <Description>.\n```\n\nWhen updating the changelog:\n1. Use `git log <last-release-commit>..HEAD` to find commits since the last release.\n2. Skip automated commits (e.g. `Auto generate ...`) and test-only commits.\n3. Group entries under **Bug Fixes**, **Improvements**, or **Breaking Changes**.\n4. Link GitHub issues when referenced in commit messages (search for `Fixes`/`Closes`/`#` in commit bodies).\n5. The unreleased section sits above the last release entry.\n6. Write for users, not maintainers: describe the symptom and user-visible outcome. Omit implementation details (internal variable names, struct names, code paths). One or two sentences max.\n\n## Files That Should Not Be Edited\n\n- `docs/reference/options.md` - Auto-generated from Nix module options\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\nWhen creating git commits, add entry to CHANGELOG.md (skip for src/modules/* and docs/* and refactorings not affecting behavior):\n\n## Build & Development Commands\n\nUse `devenv shell` to get a shell with Rust and all dependencies installed.\nPrefix commands with `devenv shell --` to run them directly.\n\n- **Build**: `cargo build`\n- **Run CLI**: `cargo run -- [args]`\n- **Build with Nix**: `nix build`\n- **Format**: `cargo fmt`\n- **Lint**: `cargo clippy`\n- **Run all tests**: `devenv-run-tests run tests`\n- **Run single test**: `devenv-run-tests run tests --only <test_name>`\n- **Run unit tests**: `cargo nextest run`\n- **Run unit tests (single crate)**: `cargo nextest run -p <crate_name>`\n- **Run all unit tests (including feature-gated)**: `cargo nextest run --features devenv/test-all`\n\n## Architecture Overview\n\ndevenv is a Rust CLI tool that creates fast, declarative, reproducible developer environments using Nix. The codebase is organized as a Cargo workspace.\n\n### Core Crates\n\n- **devenv/** - Main CLI binary. Entry point is `main.rs` which handles three runtime modes (TUI, legacy CLI, tracing). Command dispatch happens in `devenv.rs`. CLI definitions use clap in `cli.rs`.\n\n- **devenv-core/** - Shared types and abstractions:\n  - `config.rs` - Configuration parsing (`devenv.yaml`, `devenv.local.yaml`)\n  - `evaluator.rs` - The `Evaluator` trait that abstracts Nix evaluation\n  - `store.rs` - The `Store` trait for talking to a Nix store\n  - `backend.rs` - `Backend<E>`, devenv-shaped facade over an `Evaluator`\n  - `paths.rs` - `DevenvPaths` on-disk layout\n\n- **devenv-nix-backend/** - C FFI-based Nix backend using `nix-bindings-*` crates. Provides direct API access to Nix without subprocess spawning. This is the default backend.\n\n- **devenv-snix-backend/** - Experimental pure-Rust Nix evaluator backend using Snix (feature-gated with `snix`).\n\n- **devenv-tasks/** - DAG-based task execution system with caching, parallel execution, and privilege escalation support.\n\n- **devenv-activity/** - Tracing-based activity system that powers the TUI progress display. Use `#[instrument_activity(\"description\")]` macro for TUI-visible operations.\n\n- **devenv-tui/** - Terminal UI for displaying build progress and activities.\n\n- **devenv-eval-cache/** - SQLite-based caching for Nix evaluation results. Tracks file and env dependencies to invalidate cache.\n\n- **devenv-cache-core/** - Shared utilities for file hashing and SQLite operations used by both eval and task caches.\n\n- **devenv-run-tests/** - Test harness for integration tests. Runs tests in isolated temp directories with fresh environments.\n\n- **tokio-shutdown/** - Graceful shutdown manager handling SIGINT/SIGTERM with cleanup coordination.\n\n- **nix-conf-parser/** - Parser for `nix.conf` format (output of `nix config show`).\n\n- **xtask/** - Build automation (manpage and shell completion generation).\n\n### Configuration Flow\n\n1. User creates `devenv.yaml` (inputs) and `devenv.nix` (configuration)\n2. `Config::load()` in devenv-core parses YAML and resolves inputs\n3. `Devenv::assemble()` generates a temporary flake structure in `.devenv/`\n4. `NixBackend` evaluates the flake to produce shell environment or build outputs\n\n### Key Patterns\n\n- **Dual Backend Architecture**: The `NixBackend` trait allows swapping between the FFI-based backend (default) and Snix backend.\n- **Activity Tracing**: Use `#[instrument_activity(\"description\")]` macro or `activity!(INFO, operation, \"...\")` for TUI-visible operations.\n- **Error Handling**: Use `miette` for errors with `bail!()` and `?`. Custom error types use `thiserror`.\n- **SQLite Migrations**: Both `devenv-eval-cache` and `devenv-tasks` use sqlx with migrations in `migrations/` directories.\n\n## Testing\n\nIntegration tests live in `tests/` and `examples/` directories. Each test is a directory containing:\n- `devenv.nix` - The configuration to test\n- `.test.sh` - Test script (runs inside devenv shell by default)\n- `.test-config.yml` (optional) - Test configuration:\n  - `use_shell: false` - Run `.test.sh` directly, not in devenv shell\n  - `git_init: false` - Don't initialize git repo in temp dir\n  - `supported_systems` / `broken_systems` - Platform filtering\n\n### Cargo Feature Flags\n\n- **`devenv/test-all`** — Enables all feature-gated unit tests across the workspace.\n  Propagates to `devenv-processes/test-all`, `devenv-nix-backend/test-all`, `devenv-reload/test-all`, `devenv-shell/test-all`, and `devenv-tui/test-all`.\n- **`devenv/test-mcp`** — Enables MCP-related tests.\n- **`devenv/snix`** — Enables the experimental Snix backend.\n- **`devenv-shell/test-pty`** — Enables PTY-based session tests (requires a real terminal).\n- **`deterministic-tui`** — Available on both `devenv-shell` and `devenv-tui`.\n  Replaces spinner animation and elapsed time formatting with static placeholders (`[TIME]`, fixed spinner frame) so that TUI snapshot tests produce deterministic output.\n  Enabled automatically by `test-all` on both crates.\n\n\n## Tracing / Debugging\n\nTracing is disabled by default.\nEnable it with `--trace-to` using the syntax `[format:]destination`.\nMultiple outputs can be active simultaneously by repeating the flag.\n\n- **Trace to stderr**: `cargo run -- --trace-to stderr shell`\n- **Trace to file**: `cargo run -- --trace-to file:/tmp/devenv.log shell`\n- **Pretty format**: `cargo run -- --trace-to pretty:stderr shell`\n- **JSON format** (default): `cargo run -- --trace-to json:stderr shell`\n- **Full format**: `cargo run -- --trace-to full:stderr shell`\n- **Multiple outputs**: `cargo run -- --trace-to pretty:stderr --trace-to json:file:/tmp/trace.json shell`\n\nWhen format is omitted, defaults to json.\nWhen any output targets stdout or stderr, the TUI is automatically disabled.\n\nEnvironment variable `DEVENV_TRACE_TO` accepts comma-separated specs (e.g. `DEVENV_TRACE_TO=pretty:stderr,json:file:/tmp/t.json`).\n\n### Authoring trace events\n\n`tracing` (`trace!`, `debug!`, `info!`, `warn!`, `error!`) is for **developers** debugging devenv itself — visible via `--trace-to` or `RUST_LOG`.\n**User-facing output is the activity system**, not `tracing`.\nUse `activity!(...)`, `instrument_activity`, or `message(level, \"...\")` to surface anything the user should see in the TUI or non-TUI console.\n\nLevel choice:\n\n- `error!` — operation failed, user needs to know.\n- `warn!` — degraded path that succeeded (fallback used, retry happened).\n- `info!` — major lifecycle events worth noting in a normal run.\n- `debug!` — diagnostics useful when something goes wrong (cache hits/misses, decision points, request boundaries). Enabled by `--verbose`. Cost: small.\n- `trace!` — fine-grained internal flow (per-iteration, per-byte, per-state-transition). Enabled only by explicit `RUST_LOG=trace`. Cost: can be hot.\n\nRule of thumb: if an operator debugging a production issue would want it → `debug!`. If only the library author tracing internal flow would want it → `trace!`.\n\nMessage style: lowercase, no leading capital, no trailing period. Structured fields carry the data. Examples:\n\n```rust\ndebug!(key_hash = %key, \"cache hit\");\ntrace!(error = %e, \"task join error\");\nwarn!(path = %p.display(), \"failed to read file, falling back to default\");\n```\n\n## Code Style\n\n- **Error Handling**: Use `bail!()` not `panic!()`, propagate with `?`\n- **No unsafe**: Don't use `unsafe` code\n\n## Docs\n\nWhen adding documentation in `docs/`, make sure to note the version the change was added in by checking `Cargo.toml`.\n\n    !!! tip \"New in version X.Y.Y\"\n\n## Changelog\n\n\n`CHANGELOG.md` follows this structure:\n\n```\n## <version> (unreleased)\n\n### Bug Fixes\n\n- Fixed <description> ([#<issue>](https://github.com/cachix/devenv/issues/<issue>)).\n\n### Improvements\n\n- <Description of improvement>.\n\n### Breaking Changes\n\n- **<Name>**: <Description>.\n```\n\nWhen updating the changelog:\n1. Use `git log <last-release-commit>..HEAD` to find commits since the last release.\n2. Skip automated commits (e.g. `Auto generate ...`) and test-only commits.\n3. Group entries under **Bug Fixes**, **Improvements**, or **Breaking Changes**.\n4. Link GitHub issues when referenced in commit messages (search for `Fixes`/`Closes`/`#` in commit bodies).\n5. The unreleased section sits above the last release entry.\n6. Write for users, not maintainers: describe the symptom and user-visible outcome. Omit implementation details (internal variable names, struct names, code paths). One or two sentences max.\n\n## Files That Should Not Be Edited\n\n- `docs/reference/options.md` - Auto-generated from Nix module options\n","category":"root","tokens":2159}]}