Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(state): distinguish reading the cache from resolving it (#3028)

Maximilian Roos6df9623e232f
diff --git a/docs/content/config.md b/docs/content/config.md
index b55ca7e48..520c024a1 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -838,6 +838,8 @@ In a hook or alias template, prefer the `{{ default_branch }}` [template variabl
Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` to re-detect.
+`default-branch get` resolves the value and caches it on a miss; the aggregate `wt config state get` only reports the cache (read-only), so it can show `(none)` until something populates it.
+
### Detection
Worktrunk detects the default branch automatically:
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index a356f3036..63b8014b3 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -868,6 +868,8 @@ In a hook or alias template, prefer the `{{ default_branch }}` [template variabl
Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` to re-detect.
+`default-branch get` resolves the value and caches it on a miss; the aggregate `wt config state get` only reports the cache (read-only), so it can show `(none)` until something populates it.
+
### Detection
Worktrunk detects the default branch automatically:
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 88ec10c6c..477f4d769 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -709,6 +709,8 @@ In a hook or alias template, prefer the `{{ default_branch }}` [template variabl
Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` to re-detect.
+`default-branch get` resolves the value and caches it on a miss; the aggregate `wt config state get` only reports the cache (read-only), so it can show `(none)` until something populates it.
+
## Detection
Worktrunk detects the default branch automatically:
diff --git a/src/commands/config/state.rs b/src/commands/config/state.rs
index 9f90dbb48..cc62645e1 100644
--- a/src/commands/config/state.rs
+++ b/src/commands/config/state.rs
@@ -30,6 +30,17 @@
//! `handle_state_clear_all`, plus the `after_long_help` blocks for `state get`
//! and `state clear` in `src/cli/config.rs`, in the same change.
//!
+//! # Reading vs resolving
+//!
+//! The aggregate `state get` is pure inspection: it reports stored values
+//! read-only and never detects, fetches, or persists (`default-branch` via
+//! `cached_default_branch()`, CI via `CachedCiStatus::list_all`). A per-key
+//! `get` for a *derived* value resolves it and caches the result
+//! (`default-branch get` -> `default_branch()`, `ci-status get` ->
+//! `PrStatus::detect`); for stored-only values (`previous-branch`, `marker`)
+//! it is a plain read. So a `clear` followed by the aggregate `get` shows the
+//! value gone, while the per-key `get` would re-resolve it.
+//!
//! # Log layout invariant
//!
//! Inside `wt_logs_dir()`, top-level *files* are shared logs (`commands.jsonl*`,
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
index f05d17574..727818b81 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
@@ -72,6 +72,8 @@ In a hook or alias template, prefer the {{ default_branch }} template va
Without a subcommand, runs get. Use set to override, or clear then get to re-detect.
+default-branch get resolves the value and caches it on a miss; the aggregate wt config state get only reports the cache (read-only), so it can show (none) until something populates it.
+
Detection
Worktrunk detects the default branch automatically: