Skip to content

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.rs
index 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.rs
index 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.rs
index 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. A
diff --git a/src/git/mod.rs b/src/git/mod.rs
index 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 a
diff --git a/src/git/repository/diff.rs b/src/git/repository/diff.rs
index 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.rs
index 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);