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.rsindex 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.rsindex 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.