Skip to content

Add include_optional and CLI --theme precedence - #342

Merged
l1a merged 1 commit into
mainfrom
feature/include-optional
Nov 21, 2026
Merged

l1a merged 1 commit into
mainfrom
feature/include-optional

Conversation

@l1a

@l1a l1a commented Nov 20, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds include_optional, path error context on config/include file reads, and CLI --theme override precedence in retch (v0.23.0) so external theme engines (such as Noctalia) can manage a color fragment cleanly.

What changed

  • include_optional (src/config.rs, src/main.rs):
    • Accepts a string path or array of paths, merging in order: include (left-to-right) < include_optional (left-to-right) < including file.
    • Silently skips only std::io::ErrorKind::NotFound; directories, non-regular files, permission errors, oversized files (> 1 MiB), invalid TOML, empty path entries, depth overflow (> 8), cycles, and missing nested required include targets still fail loudly.
    • Added DEFAULT_INCLUDE_OPTIONAL_BLOCK to --generate-config, --write-config, and --merge-config without using any other key's name = assignment syntax in comments.
  • Missing-path error context (src/config.rs):
    • read_config_bytes attaches .with_context(|| format!("Failed to read config {}", path.display())) on metadata/open/read failures so errors always identify the offending file.
  • CLI --theme precedence (src/config.rs, src/display.rs):
    • Extracted display::resolve_theme and updated Config::merge_with_cli so passing --theme <name> (for any value other than "custom", case-insensitive) ignores [custom_theme] overrides from config files while preserving --theme custom.
  • Versioning & Docs (Cargo.toml, Cargo.lock, docs/retch.1.md, docs/retch.1, README.md, NOTES.md, retch.wiki):
    • Bumped retch-cli to 0.23.0 (retch-sysinfo unchanged at 0.1.111), regenerated docs/retch.1, and updated documentation (including Configuration-and-Theming.md in retch.wiki).

Test plan

  • just check passes (cargo fmt -- --check, cargo clippy --workspace -- -D warnings, cargo clippy -p retch-cli --no-default-features -- -D warnings, man_pages.py, packaging/metadata/text/wip/bench checks)
  • cargo test --workspace passes (including new include_optional, error-context, --merge-config, and CLI --theme precedence unit tests in src/config.rs and src/display.rs, plus test_cli_include_optional_and_theme_override in tests/cli_tests.rs)
  • Verify in a live terminal with a config.toml setting include_optional = "themes/noctalia.toml" (both when the fragment is absent and when present) and confirm retch --theme solarized-dark overrides it while retch --theme custom keeps it

Note

Medium Risk
Changes config merge semantics and theme resolution paths users rely on for theming, but does not touch auth, network payloads, or privileged operations beyond clearer config read errors.

Overview
Bumps retch-cli to 0.23.0 and refines how config.toml loads fragments and applies themes for external template workflows (e.g. Noctalia).

include_optional merges like include, but only NotFound is ignored; invalid TOML, cycles, oversized files, and nested required include failures still error. Merge order is required include → include_optional → this file, with empty path strings rejected.

CLI --theme (any name except "custom", case-insensitive) now wins over [custom_theme] from included files via resolve_theme in display.rs and by clearing custom_theme in Config::merge_with_cli.

Config I/O errors attach the offending path through anyhow::Context in read_config_bytes. Docs, man page, and default config templates document include_optional; Homebrew packaging avoids literal @TOKEN@ in comments and render_packaging.py --self-test enforces rendered formula lines ≤ 118 characters.

Reviewed by Cursor Bugbot for commit 35b1603. Bugbot is set up for automated code reviews on this repo. Configure here.

Support optional config/theme includes, missing-path error context,
and CLI --theme override precedence for retch v0.23.0:

- Add `include_optional` (string or array) merged after required
  `include` files and before the including file's own keys; skip only
  `ErrorKind::NotFound` while still failing on directories, permission
  errors, invalid TOML, empty paths, size/depth limits, cycles, and
  nested required `include` failures
- Attach path context via `anyhow::Context` in `read_config_bytes`
- Ignore `[custom_theme]` overrides when `--theme <name>` is passed on
  the CLI with any value other than `"custom"` (`Config::merge_with_cli`
  and `display::resolve_theme`)
- Add unit and CLI integration tests covering `include_optional`,
  error context, `--merge-config` doc safety, and `--theme` precedence
- Fix `packaging/homebrew/retch.rb` header comment exceeding Homebrew's
  118-char line limit when rendered, and enforce line length in
  `scripts/render_packaging.py --self-test`
- Bump `retch-cli` to `0.23.0`, update `Cargo.lock`, regenerate
  `docs/retch.1`, and update `README.md` and `NOTES.md`

Assisted-By: Gemini
@l1a
l1a force-pushed the feature/include-optional branch from 4f4ca5a to 35b1603 Compare November 20, 2026 23:50
@l1a
l1a merged commit 861fb43 into main Nov 21, 2026
24 checks passed
@l1a
l1a deleted the feature/include-optional branch November 21, 2026 00:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant