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