Skip to content

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

docs: clarify stale branch heuristic and cost drivers

Maximilian Roos85f38cdbd4f3
diff --git a/src/commands/list/collect.rs b/src/commands/list/collect.rs
index ad3fc3966..0e2673b78 100644
--- a/src/commands/list/collect.rs
+++ b/src/commands/list/collect.rs
@@ -1046,10 +1046,14 @@ pub fn collect(
// counts in a single command. On older git versions, returns empty and all tasks run.
// Skip if default_branch is unknown.
if skip_expensive_for_stale && let Some(ref db) = default_branch {
- // Branches more than 50 commits behind skip expensive merge-base operations.
+ // Branches more than 50 commits behind skip expensive operations.
// 50 is low enough to catch truly stale branches while keeping info for
- // recently-diverged ones. The "behind" count is the primary expense driver -
- // git must traverse all those commits to find the merge-base.
+ // recently-diverged ones.
+ //
+ // "Behind" is a proxy for the actual cost driver: files changed on both
+ // sides since the merge-base. More commits on main → more files touched →
+ // more overlap with the branch. See `CollectOptions::stale_branches` for
+ // detailed rationale.
let threshold: usize = std::env::var("WORKTRUNK_TEST_SKIP_EXPENSIVE_THRESHOLD")
.ok()
.and_then(|s| s.parse().ok())
diff --git a/src/commands/list/collect_progressive_impl.rs b/src/commands/list/collect_progressive_impl.rs
index 15f448501..087ba775e 100644
--- a/src/commands/list/collect_progressive_impl.rs
+++ b/src/commands/list/collect_progressive_impl.rs
@@ -55,6 +55,26 @@ pub struct CollectOptions {
/// Presence in set = skip expensive tasks for this branch (HasFileChanges,
/// IsAncestor, WouldMergeAdd, BranchDiff, MergeTreeConflicts).
///
+ /// ## Why "commits behind" as the heuristic
+ ///
+ /// The expensive operations (`git merge-tree`, `git diff`) scale with:
+ /// - **Files changed on both sides** — each needs 3-way merge or diff
+ /// - **Size of those files** — content loading and merge algorithm
+ ///
+ /// Commit count isn't directly in the algorithm, but "commits behind" is a
+ /// cheap proxy: more commits on main since divergence → more files main has
+ /// touched → more potential overlap with the branch's changes.
+ ///
+ /// We use "behind" rather than "ahead" because feature branches typically
+ /// have small ahead counts, so behind dominates. A more accurate heuristic
+ /// would be `min(files_changed_on_main, files_changed_on_branch)`, but
+ /// computing that requires per-branch git commands, defeating the optimization.
+ ///
+ /// The batch `git for-each-ref --format='%(ahead-behind:...)'` gives us all
+ /// counts in a single command, making this heuristic essentially free.
+ ///
+ /// ## Implementation
+ ///
/// Built by filtering `batch_ahead_behind()` results on local branches only.
/// Remote-only branches are never in this set (they use individual git commands).
/// The threshold (default 50) is applied at construction time. Ahead/behind