Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: correct docstrings that describe a removed ref cache and wrong validation examples (#4374)
Worktrunk Bot531113892b43
diff --git a/src/commands/list/collect/mod.rs b/src/commands/list/collect/mod.rsindex 5c6a706b6..1e5ac0565 100644--- a/src/commands/list/collect/mod.rs+++ b/src/commands/list/collect/mod.rs@@ -579,8 +579,8 @@ pub struct CollectOptions {/// Built once during the pre-skeleton phase (or during single-item/// population) and shared (cheaply, behind `Arc`) into every task./// Tasks resolve target ref names to commit SHAs through this snapshot,- /// then call the `_by_sha` variants of cached methods — bypassing the- /// ambient ref→SHA cache entirely. The full list path may include+ /// then call the `_by_sha` variants of cached methods, so every task+ /// reads the same point-in-time ref state. The full list path may include/// batched ahead/behind data; single-item callers intentionally use a/// plain ref snapshot and let per-row tasks fall back to per-pair/// queries. `None` when capture failed (degraded mode).diff --git a/src/commands/list/collect/tasks.rs b/src/commands/list/collect/tasks.rsindex a171b1a52..d6ba658cf 100644--- a/src/commands/list/collect/tasks.rs+++ b/src/commands/list/collect/tasks.rs@@ -81,8 +81,8 @@ pub struct TaskContext {pub integration_targets: Option<IntegrationTargets>,/// Captured ref state for this list invocation. Tasks resolve ref/// names to commit SHAs through this snapshot before calling- /// `_by_sha` methods on `Repository`, side-stepping the ambient- /// ref→SHA cache. `None` when snapshot capture failed (degraded+ /// `_by_sha` methods on `Repository`, so every task reads the same+ /// point-in-time ref state. `None` when snapshot capture failed (degraded/// mode — tasks fall back to ref-taking methods).pub snapshot: Option<Arc<RefSnapshot>>,}diff --git a/src/config/expansion.rs b/src/config/expansion.rsindex 898634e1c..3f0363b7d 100644--- a/src/config/expansion.rs+++ b/src/config/expansion.rs@@ -199,7 +199,7 @@ impl VarScope<'_> {#[derive(Debug, Clone, Copy)]pub enum ValidationScope {/// A hook of the given type. Adds hook infrastructure vars (`hook_type`,- /// `hook_name`) plus hook-specific vars (`base`, `target`, etc.).+ /// `hook_name`), hook-specific vars (`base`, `target`, etc.), and `args`.Hook(HookType),/// The `--execute` template or trailing args for `wt switch --create`./// Adds `base` / `base_worktree_path` for the source worktree.@@ -996,8 +996,8 @@ pub fn validate_template_syntax(template: &str, name: &str) -> Result<(), Templa/// Performs a trial expansion with placeholder values for exactly the variables/// available in `scope` (see [`vars_available_in`]). Catches syntax errors and/// undefined variable references *before* irreversible operations like worktree-/// creation — including context-mismatch typos like `{{ args }}` in a hook or-/// `{{ target }}` in a `pre-start` hook.+/// creation — including context-mismatch typos like `{{ base }}` in a+/// `pre-merge` hook or `{{ args }}` in a `--execute` template.////// This is deliberately more permissive than real expansion: conditional vars/// like `upstream` are provided even when they may be absent at runtime. Adiff --git a/src/git/mod.rs b/src/git/mod.rsindex f99960cd6..408df12e4 100644--- a/src/git/mod.rs+++ b/src/git/mod.rs@@ -272,7 +272,7 @@ pub fn check_integration(signals: &IntegrationSignals) -> Option<IntegrationReas/// For batch operations, use parallel tasks to build [`IntegrationSignals`] directly.////// Resolves both `branch` and `target` to commit SHAs via `snapshot` so the-/// integration probes are immune to ambient ref→SHA cache staleness — this+/// integration probes read the ref state the caller captured — this/// is the safety contract that lets `wt merge`'s post-update-ref check/// observe the new local target SHA instead of the pre-merge value./// Refs not in the snapshot (typically transient HEAD commits during adiff --git a/src/git/repository/diff.rs b/src/git/repository/diff.rsindex 7b6415c50..27d8dbf4c 100644--- a/src/git/repository/diff.rs+++ b/src/git/repository/diff.rs@@ -457,8 +457,7 @@ impl Repository {/// SHA-keyed variant of [`Self::merge_base`].///- /// Inputs are commit SHAs. Skips the ambient ref→SHA conversion- /// entirely; cache key is `(min(sha1, sha2), max(sha1, sha2))`.+ /// Inputs are commit SHAs, so no ref names are resolved; cache key is `(min(sha1, sha2), max(sha1, sha2))`.////// In-memory front over a persistent disk back/// (`merge-base/{min}-{max}.json`): the `DashMap` dedups within one@@ -585,7 +584,7 @@ impl Repository {/// SHA-keyed variant of [`Self::branch_diff_stats`].///- /// Inputs are commit SHAs. Bypasses the ambient ref→SHA cache.+ /// Inputs are commit SHAs, so no ref names are resolved.pub fn branch_diff_stats_by_sha(&self,base_sha: &str,diff --git a/src/git/repository/integration.rs b/src/git/repository/integration.rsindex 57ba4de70..4480134b7 100644--- a/src/git/repository/integration.rs+++ b/src/git/repository/integration.rs@@ -151,8 +151,8 @@ pub(in crate::git) enum MergeTreeOutcome {impl Repository {/// Check if `base_sha` is an ancestor of `head_sha`, taking commit SHAs- /// directly. Hits the persistent SHA-keyed cache without going through- /// the (stale-prone) ambient ref→SHA cache.+ /// directly. Hits the persistent SHA-keyed cache without resolving any+ /// ref names.////// Callers that hold SHAs (e.g., from a `RefSnapshot` or a/// `BranchRef.commit_sha`) should prefer this form.@@ -175,9 +175,9 @@ impl Repository {/// For orphan branches (no common ancestor with target), returns true since all/// their changes are unique.///- /// Bypasses the ambient ref→SHA cache so callers holding SHAs from a- /// [`RefSnapshot`] (or `BranchRef.commit_sha`) can short-circuit to the- /// persistent SHA-keyed cache directly.+ /// Takes commit SHAs, so callers holding SHAs from a [`RefSnapshot`] (or+ /// `BranchRef.commit_sha`) go straight to the persistent SHA-keyed cache+ /// without resolving ref names.pub fn has_added_changes_by_sha(&self,branch_sha: &str,@@ -406,8 +406,9 @@ impl Repository {/// capped at [`PATCH_ID_SCAN_MAX_COMMITS`].////// Returns `Ok(true)` if a matching squash-merge commit is found on the target,- /// `Ok(false)` otherwise (including when the target history is too deep to scan,- /// or when patch-id computation fails — both conservative).+ /// `Ok(false)` otherwise (including when the target history is too deep to+ /// scan — conservative). A failing git command propagates as `Err`; the+ /// caller treats that as no match.fn is_squash_merged_via_patch_id(&self, branch: &str, target: &str) -> anyhow::Result<bool> {let Some(merge_base) = self.merge_base(target, branch)? else {return Ok(false);