Skip to content

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

docs(collect): document cache design across `.git/wt/cache/` (#2097)

Maximilian Roos523bae2fe424
diff --git a/src/commands/list/collect/mod.rs b/src/commands/list/collect/mod.rs
index 3fceeeda4..5c3bd00eb 100644
--- a/src/commands/list/collect/mod.rs
+++ b/src/commands/list/collect/mod.rs
@@ -92,6 +92,69 @@
//! **Task ordering**: Work items are sorted so local git operations run first, network tasks
//! (CI status, URL health checks) run last. This ensures the table fills in quickly with local
//! data while slower network requests complete in the background.
+//!
+//! ## Caching
+//!
+//! Four sibling caches live under `.git/wt/cache/`. Each uses a different key scheme because
+//! the underlying operations differ in what their output depends on.
+//!
+//! | Directory | Module | Key | Staleness |
+//! |-----------|--------|-----|-----------|
+//! | `merge-tree-conflicts/` | `git::repository::probe_cache` | `{sha1}-{sha2}.json` (sorted) | Never — content-addressed |
+//! | `merge-add-probe/` | `git::repository::probe_cache` | `{branch_sha}-{target_sha}.json` | Never — content-addressed |
+//! | `ci-status/` | `commands::list::ci_status::cache` | `{branch}.json` | TTL 30–60s + HEAD SHA check |
+//! | `summaries/` | `summary` | `{branch}.json` | `diff_hash` mismatch |
+//!
+//! ### Key schemes
+//!
+//! - **SHA-pair**: pure function of two commit SHAs. Never stale, no TTL, no invalidation.
+//! Used by merge-tree conflict checks and merge-add probes.
+//! - **Branch + TTL + HEAD**: external mutable state (CI API, remote refs). TTL bounds
+//! staleness; the HEAD check invalidates early when the branch moves.
+//! - **Branch + content hash**: deterministic function of a mutable input (e.g. an LLM call
+//! over a diff). Invalidates on hash mismatch.
+//!
+//! ### Which tasks hit which cache
+//!
+//! | Task | Cache |
+//! |------|-------|
+//! | `MergeTreeConflicts` | `probe_cache` (merge-tree-conflicts) |
+//! | `WouldMergeAdd` | `probe_cache` (merge-add-probe) |
+//! | `CiStatus` | `ci_status::cache` |
+//! | `SummaryGenerate` | `summary` |
+//!
+//! Every other task re-runs on each invocation.
+//!
+//! ### Cacheable but uncached
+//!
+//! Several tasks compute a pure function of a commit SHA pair and slot into `probe_cache`
+//! without a new scheme:
+//!
+//! - `IsAncestor` — `merge-base --is-ancestor base head`
+//! - `HasFileChanges` — three-dot diff `target...branch`
+//! - `BranchDiff` — diff stats `base...branch`
+//!
+//! A second group takes ref *names*, but reduces to a SHA pair once the refs are resolved.
+//! Same pattern, same cache:
+//!
+//! - `AheadBehind` — counts against the default branch
+//! - `CommittedTreesMatch` — tree equality against the integration target
+//! - `Upstream` — ahead/behind counts against the tracking branch
+//!
+//! Reuse `probe_cache` for any of these rather than inventing a fourth scheme.
+//!
+//! ### Fundamentally uncacheable
+//!
+//! Some task outputs depend on state outside the commit graph:
+//!
+//! - `WorkingTreeDiff`, `WorkingTreeConflicts` — uncommitted changes and index state
+//! - `GitOperation` — presence of `.git/rebase-merge`, `.git/rebase-apply`, or `MERGE_HEAD`
+//! - `UserMarker` — local git config value
+//! - `UrlStatus` — TCP connect to a local dev server port; real-time by nature
+//!
+//! All but `UrlStatus` are cheap enough that caching would not pay back. `UrlStatus` is
+//! bounded at 50ms per item; a stale "active" result when the server just died is worse
+//! than the probe cost.
mod execution;
mod results;
diff --git a/src/git/repository/probe_cache.rs b/src/git/repository/probe_cache.rs
index dba3485c9..b2f12c96a 100644
--- a/src/git/repository/probe_cache.rs
+++ b/src/git/repository/probe_cache.rs
@@ -10,8 +10,10 @@
//!
//! One file per cached entry under `.git/wt/cache/{kind}/{key}.json`,
//! where `kind` is the task kind (`merge-tree-conflicts`,
-//! `merge-add-probe`) and `key` is the SHA-pair filename. This is the
-//! same top-level layout as `ci-status/` and `summaries/`.
+//! `merge-add-probe`) and `key` is the SHA-pair filename. The sibling
+//! `ci-status/` and `summaries/` caches use different key schemes; see
+//! `commands::list::collect` for the cross-cutting design across all
+//! four caches.
//!
//! Symmetric kinds (merge-tree-conflicts) sort the SHA pair so
//! `merge-tree(A, B)` and `merge-tree(B, A)` hit the same entry.