Skip to content

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

bench(list): consolidate synthetic `wt list` benches into one `full` group (#3335)

Maximilian Roos28c937dbbf7e
diff --git a/benches/CLAUDE.md b/benches/CLAUDE.md
index 0a414fa4b..f00966c0c 100644
--- a/benches/CLAUDE.md
+++ b/benches/CLAUDE.md
@@ -11,7 +11,7 @@ Criterion's CLI takes a positional `FILTER` (substring inclusion) and `--exact`.
cargo bench --bench list skeleton/warm
# Run specific group (all variants)
-cargo bench --bench list many_branches
+cargo bench --bench list full
# GH #461 scenario (200 branches on rust-lang/rust)
cargo bench --bench list real_repo_many_branches
@@ -34,17 +34,20 @@ Real repo benchmarks clone rust-lang/rust on first run (~2-5 minutes). The clone
## Faster Iteration
-Criterion has no exclusion flag — narrow the run by picking a substring that matches only the variants you want. Benchmark IDs look like `<group>/<label>/<param>`, e.g. `skeleton/cold/4`, `worktree_scaling/warm/8`, `real_repo_many_branches/warm`.
+Criterion has no exclusion flag — narrow the run by picking a substring that matches only the variants you want. Benchmark IDs look like `<group>/<label>/<param>`, e.g. `skeleton/cold/4`, `worktree_scaling/warm/8`, `full/cold`, `real_repo_many_branches/warm`.
**Pattern matching (positional `FILTER`):**
```bash
cargo bench --bench list scaling # All worktree_scaling/* variants
cargo bench --bench list warm # Every benchmark whose ID contains "warm"
cargo bench --bench list skeleton/warm # Just skeleton's warm variants
-cargo bench --bench list -- --exact full/cold/4 # One exact ID
+cargo bench --bench list full # Both cache states of the combined fixture
+cargo bench --bench list -- --exact full/cold # One exact ID
```
-To skip the slow real-repo and divergent groups, target the synthetic groups directly: `cargo bench --bench list skeleton`, `cargo bench --bench list full`, or `cargo bench --bench list worktree_scaling`. Run them sequentially if you want more than one.
+To skip the slow real-repo and divergent groups, target the synthetic groups directly: `cargo bench --bench list skeleton`, `cargo bench --bench list worktree_scaling`, or `cargo bench --bench list full`. Run them sequentially if you want more than one.
+
+The `full` group is the place to start when `wt list` regresses on a real mix of worktrees and branches: the cold/warm split says whether the cost is the persistent-cache fill (cold) or the per-process re-fork (warm). A `full` wall time can't be split by side (the git subprocesses overlap on the rayon pool), so to localize a regression, trace one invocation and bucket subprocess time per worktree (query #3 below); `worktree_scaling` and `divergent_branches` track the worktree side and branch side respectively at criterion cadence.
## WORKTRUNK_FIRST_OUTPUT
@@ -164,6 +167,7 @@ cargo run -p wt-perf -- setup typical-8 --persist
# branches-N - N branches, 1 commit each
# branches-N-M - N branches, M commits each
# divergent - 200 branches × 20 commits (GH #461 scenario)
+# mixed-W-B - W worktrees + B branches in varied states (the `full` fixture)
# picker-test - Config for wt switch interactive picker testing
# Invalidate caches for cold run
diff --git a/benches/list.rs b/benches/list.rs
index 43363d1c5..d0044020e 100644
--- a/benches/list.rs
+++ b/benches/list.rs
@@ -1,22 +1,30 @@
// Benchmarks for `wt list` command
//
// Benchmark groups:
-// - skeleton: Time until skeleton appears (1, 4, 8 worktrees; warm + cold)
-// - full: Full execution time (1, 4, 8 worktrees; warm + cold)
-// - worktree_scaling: Worktree count scaling (1, 4, 8 worktrees; warm + cold)
+// - skeleton: Time until the skeleton paints (1, 4, 8 worktrees; warm + cold)
+// - worktree_scaling: Full execution, worktree-count scaling (1, 4, 8 worktrees; warm + cold)
+// - full: One combined full-surface fixture — many worktrees AND many branches
+// in varied states, with branch divergence spread across history depth.
+// The realistic "everything at once" workload (warm + cold).
+// - divergent_branches: 200 branches × 20 commits / GH #461 deep-divergence stress (warm + cold)
// - real_repo: rust-lang/rust clone (1, 4, 8 worktrees; warm + cold)
-// - many_branches: 100 branches (warm + cold)
-// - divergent_branches: 200 branches × 20 commits on synthetic repo (warm + cold)
// - real_repo_many_branches: 50 branches at different history depths / GH #461
// - warm: all branches (first run expensive; subsequent runs hit persistent cache)
// - warm_worktrees_only: no branch enumeration (~600ms)
-// - timeout_effect: Compare with/without 500ms command timeout on rust repo / GH #461 fix
+//
+// Attribution: a `full` wall time can't be split by side (worktree- and
+// branch-side git subprocesses overlap on the rayon pool), so to see where a
+// regression lands, trace one invocation and bucket subprocess time per
+// worktree / task type — see `benches/CLAUDE.md` ("Performance Investigation
+// with wt-perf", query #3, `args.context`). For per-side regression tracking
+// at criterion cadence, `worktree_scaling` is the worktree side and
+// `divergent_branches` the branch side.
//
// Run examples (Criterion takes a positional substring FILTER; no --skip):
// cargo bench --bench list # All benchmarks
// cargo bench --bench list skeleton # Progressive rendering
+// cargo bench --bench list full # Combined full-surface fixture
// cargo bench --bench list real_repo_many_branches # GH #461 scenario (large repo + many branches)
-// cargo bench --bench list timeout_effect # Test timeout fix for GH #461
// cargo bench --bench list warm # Warm-cache variants (every group's warm rows)
// cargo bench --bench list skeleton/warm # Skeleton group, warm only
@@ -44,13 +52,6 @@ impl BenchConfig {
}
}
- const fn branches(count: usize, commits_per_branch: usize, cold_cache: bool) -> Self {
- Self {
- repo: RepoConfig::branches(count, commits_per_branch),
- cold_cache,
- }
- }
-
const fn many_divergent_branches(cold_cache: bool) -> Self {
Self {
repo: RepoConfig::many_divergent_branches(),
@@ -63,12 +64,17 @@ impl BenchConfig {
}
}
-/// Run a benchmark with the given config.
+/// Run `wt` with `args` in `repo_path`, on a warm or cold cache.
+///
+/// Fixture-agnostic: callers build whatever repo shape they want, then pass
+/// `cold_cache` to pick the iteration strategy. Warm uses plain `b.iter`
+/// (caches stay warm across iterations); cold invalidates before every
+/// measured iteration.
fn run_benchmark(
b: &mut criterion::Bencher,
binary: &Path,
repo_path: &Path,
- config: &BenchConfig,
+ cold_cache: bool,
args: &[&str],
env: Option<(&str, &str)>,
) {
@@ -82,7 +88,7 @@ fn run_benchmark(
cmd
};
- if config.cold_cache {
+ if cold_cache {
// `BatchSize::PerIteration` (not `SmallInput`): under `SmallInput`,
// criterion calls `setup` for an entire batch up front and then runs
// the timed routines back-to-back — so only the first `wt` per batch
@@ -123,7 +129,7 @@ fn bench_skeleton(c: &mut Criterion) {
b,
binary,
&repo_path,
- config,
+ config.cold_cache,
&["list"],
Some(("WORKTRUNK_SKELETON_ONLY", "1")),
);
@@ -135,30 +141,6 @@ fn bench_skeleton(c: &mut Criterion) {
group.finish();
}
-fn bench_full(c: &mut Criterion) {
- let mut group = c.benchmark_group("full");
- let binary = Path::new(env!("CARGO_BIN_EXE_wt"));
-
- for worktrees in [1, 4, 8] {
- for cold in [false, true] {
- let config = BenchConfig::typical(worktrees, cold);
-
- group.bench_with_input(
- BenchmarkId::new(config.label(), worktrees),
- &config,
- |b, config| {
- let temp = create_repo(&config.repo);
- let repo_path = temp.path().join("repo");
- setup_fake_remote(&repo_path);
- run_benchmark(b, binary, &repo_path, config, &["list"], None);
- },
- );
- }
- }
-
- group.finish();
-}
-
fn bench_worktree_scaling(c: &mut Criterion) {
let mut group = c.benchmark_group("worktree_scaling");
let binary = Path::new(env!("CARGO_BIN_EXE_wt"));
@@ -174,7 +156,7 @@ fn bench_worktree_scaling(c: &mut Criterion) {
let temp = create_repo(&config.repo);
let repo_path = temp.path().join("repo");
run_git(&repo_path, &["status"]);
- run_benchmark(b, binary, &repo_path, config, &["list"], None);
+ run_benchmark(b, binary, &repo_path, config.cold_cache, &["list"], None);
},
);
}
@@ -245,31 +227,6 @@ fn bench_real_repo(c: &mut Criterion) {
group.finish();
}
-fn bench_many_branches(c: &mut Criterion) {
- let mut group = c.benchmark_group("many_branches");
- let binary = Path::new(env!("CARGO_BIN_EXE_wt"));
-
- for cold in [false, true] {
- let config = BenchConfig::branches(100, 2, cold);
-
- group.bench_function(config.label(), |b| {
- let temp = create_repo(&config.repo);
- let repo_path = temp.path().join("repo");
- run_git(&repo_path, &["status"]);
- run_benchmark(
- b,
- binary,
- &repo_path,
- &config,
- &["list", "--branches", "--progressive"],
- None,
- );
- });
- }
-
- group.finish();
-}
-
fn bench_divergent_branches(c: &mut Criterion) {
let mut group = c.benchmark_group("divergent_branches");
group.measurement_time(std::time::Duration::from_secs(30));
@@ -288,7 +245,7 @@ fn bench_divergent_branches(c: &mut Criterion) {
b,
binary,
&repo_path,
- &config,
+ config.cold_cache,
&["list", "--branches", "--progressive"],
None,
);
@@ -382,58 +339,64 @@ fn bench_real_repo_many_branches(c: &mut Criterion) {
group.finish();
}
-// TODO(bench-full-combined): promote this into one canonical "full"-scenario
-// benchmark covering lots of worktrees AND branches across cold + warm cache
-// (the existing `full` group is worktrees-only despite its name; the branch
-// groups have no worktrees). With a combined fixture, use the trace attribution
-// to isolate where the cost lands — the per-command `args.context` grouping in
-// `benches/CLAUDE.md` (query #3) buckets time per worktree, and worktree-only
-// vs branch-only variants separate worktree-side tasks (status/diff/write-tree)
-// from branch-side tasks (ahead-behind/merge-tree/integration), so a regression
-// can be pinned to a feature rather than the whole command. `rerun_warm` below
-// is the warm seed of that.
-
-/// Warm-cache re-run: many worktrees AND many branches in varied states, with
-/// `.git/wt/cache/` already populated — the steady-state "re-run `wt list`"
-/// cost a user pays on every invocation once the persistent SHA cache is warm.
+/// Combined full-surface `wt list`: many worktrees AND many branches in varied
+/// states, with branch divergence spread across history depth — the whole
+/// command exercised by one fixture instead of several narrow ones. This is the
+/// realistic "lots of worktrees & branches, all in various states" workload.
+///
+/// `create_mixed_repo` builds the spread of `wt list` gates and tasks at once:
+/// clean/dirty/staged working trees, merged/ahead/diverged branches, and the
+/// GH #461 deep-divergence shape (branches forking at points spread across
+/// history depth, so the `git for-each-ref %(ahead-behind)` walk has real
+/// history to traverse).
+///
+/// To see *where* a regression lands, trace one invocation and bucket
+/// subprocess time per worktree / task type — see `benches/CLAUDE.md`
+/// ("Performance Investigation with wt-perf", query #3, `args.context`); a
+/// criterion wall time can't be decomposed by side because the worktree- and
+/// branch-side git subprocesses run concurrently on the rayon pool. For
+/// per-side regression tracking at criterion cadence, `worktree_scaling`
+/// isolates the worktree side and `divergent_branches` the branch-side walk.
///
-/// Unlike the cold variants, this measures *irreducible per-invocation* work:
+/// Cold vs warm measure different costs. Warm (plain `b.iter`, disk SHA cache
+/// kept hot by the criterion warm-up) is the *irreducible per-invocation* work:
/// the in-memory caches (`Arc<RepoCache>`, `WORKTREE_ROOTS`, `GIT_DIRS`,
/// `commit_tree`, `merge_base`) die with each `wt` process, so every re-run
-/// re-forks whatever those cover, while the disk SHA cache (ahead-behind,
-/// is-ancestor, merge-tree, diff-stats) serves from file reads. `b.iter`
-/// (no cache invalidation) keeps the disk cache warm across iterations; the
-/// criterion warm-up populates it before the first measured run.
+/// re-forks whatever those cover while the disk SHA cache (ahead-behind,
+/// is-ancestor, merge-tree, diff-stats) serves from file reads. Cold
+/// invalidates `.git/wt/cache/` before each measured iteration, so it pays the
+/// full #461 `%(ahead-behind)` walk and every integration probe from scratch.
///
/// Runs `list --branches --progressive` to exercise both worktree and branch
/// rows on the progressive render path (matching real TTY use), without the
/// network-touching `ci` column that `--full` would add.
-fn bench_rerun_warm(c: &mut Criterion) {
- let mut group = c.benchmark_group("rerun_warm");
- // ~24 worktrees + 120 branches runs ~300ms/iter; the inherited 30-sample /
- // 15s budget can't fit 30, so cap samples at criterion's minimum and give
- // a 20s window (≈ a few iters per sample).
+fn bench_full(c: &mut Criterion) {
+ let mut group = c.benchmark_group("full");
+ // Heavy fixture (24 worktrees + 120 branches, deep history): the cold
+ // variant runs well over the inherited 30-sample / 15s budget, so cap
+ // samples at criterion's minimum and give a 20s window (≈ a few iters per
+ // sample), matching the other heavy groups.
group.measurement_time(std::time::Duration::from_secs(20));
group.sample_size(10);
let binary = Path::new(env!("CARGO_BIN_EXE_wt"));
-
let (worktrees, branches) = (24usize, 120usize);
- group.bench_with_input(
- BenchmarkId::from_parameter(format!("{worktrees}wt_{branches}br")),
- &(worktrees, branches),
- |b, &(worktrees, branches)| {
+
+ for cold in [false, true] {
+ let label = if cold { "cold" } else { "warm" };
+ group.bench_function(label, |b| {
let temp = create_mixed_repo(worktrees, branches);
let repo_path = temp.path().join("repo");
- b.iter(|| {
- let mut cmd = Command::new(binary);
- cmd.args(["list", "--branches", "--progressive"])
- .current_dir(&repo_path);
- isolate_subprocess_env(&mut cmd, None);
- cmd.output().unwrap();
- });
- },
- );
+ run_benchmark(
+ b,
+ binary,
+ &repo_path,
+ cold,
+ &["list", "--branches", "--progressive"],
+ None,
+ );
+ });
+ }
group.finish();
}
@@ -444,6 +407,6 @@ criterion_group! {
.sample_size(30)
.measurement_time(std::time::Duration::from_secs(15))
.warm_up_time(std::time::Duration::from_secs(3));
- targets = bench_skeleton, bench_full, bench_worktree_scaling, bench_real_repo, bench_many_branches, bench_divergent_branches, bench_real_repo_many_branches, bench_rerun_warm
+ targets = bench_skeleton, bench_worktree_scaling, bench_full, bench_real_repo, bench_divergent_branches, bench_real_repo_many_branches
}
criterion_main!(benches);
diff --git a/tests/helpers/wt-perf/src/lib.rs b/tests/helpers/wt-perf/src/lib.rs
index 2d68137b4..18a2d4ffc 100644
--- a/tests/helpers/wt-perf/src/lib.rs
+++ b/tests/helpers/wt-perf/src/lib.rs
@@ -536,15 +536,17 @@ fn append_line(path: &Path, rel: &str, line: &str) {
}
/// Create a repo with `worktrees` linked worktrees AND `branches` branchless
-/// branches, each in a deterministic rotation of states, for the warm-cache
-/// `wt list` re-run benchmark.
+/// branches, each in a deterministic rotation of states, for the combined
+/// full-surface `wt list` benchmark (`full` in `benches/list.rs`).
///
/// Unlike [`RepoConfig`] (every worktree/branch identical), this exercises the
-/// full spread of `wt list` gates and tasks — clean vs dirty working trees,
-/// merged vs ahead vs diverged branches — which is the realistic shape of "a
-/// huge number of worktrees & branches, all in various states". Returns the
-/// `TempDir`; the main worktree is at `temp.path().join("repo")`, linked
-/// worktrees are siblings (`repo.wt-NNNN`).
+/// full spread of `wt list` gates and tasks at once — clean vs dirty working
+/// trees, merged vs ahead vs diverged branches, *and* divergence spread across
+/// history depth — the realistic shape of "a huge number of worktrees &
+/// branches, all in various states". Returns the `TempDir`; the main worktree
+/// is at `temp.path().join("repo")`, linked worktrees are siblings
+/// (`repo.wt-NNNN`). Either dimension may be `0` (e.g. `mixed-W-0` for a
+/// worktrees-only repo).
///
/// Worktree states cycle by index % 4:
/// 0. clean, several commits ahead of base
@@ -552,10 +554,15 @@ fn append_line(path: &Path, rel: &str, line: &str) {
/// 2. staged + unstaged + untracked (full dirty mix)
/// 3. clean, sitting exactly at base
///
-/// Branch states cycle by index % 4:
-/// 0. at an older checkpoint (ancestor of base — integration-positive)
+/// Branch states cycle by index % 4 (states 0 and 2 fork at a checkpoint that
+/// slides from the oldest base commit toward the tip as the index grows, so
+/// fork depth fans out across the whole history — the GH #461 deep-divergence
+/// shape that drives the O(commits) `git for-each-ref %(ahead-behind)` walk):
+/// 0. behind: at an older checkpoint (ancestor of base —
+/// integration-positive / merged shape)
/// 1. ahead of base with its own commits (unmerged)
-/// 2. diverged: own commits from an older checkpoint while base advanced
+/// 2. diverged: a short own-commit chain forked from an older checkpoint
+/// while base advanced (deep two-sided divergence)
/// 3. identical to the base tip (trees match — squash-merge shape)
pub fn create_mixed_repo(worktrees: usize, branches: usize) -> TempDir {
let temp = tempfile::tempdir().unwrap();
@@ -568,7 +575,14 @@ pub fn create_mixed_repo(worktrees: usize, branches: usize) -> TempDir {
/// siblings.
pub fn create_mixed_repo_at(worktrees: usize, branches: usize, repo: &Path) {
const FILES: usize = 50;
- const BASE_COMMITS: usize = 120;
+ // Deep enough that fork points spread across history give the
+ // `%(ahead-behind)` walk real commits to traverse (GH #461 shape), while
+ // staying far cheaper to build than the dedicated `divergent` stress
+ // (`RepoConfig::many_divergent_branches`, 200 branches × 20 commits).
+ const BASE_COMMITS: usize = 200;
+ // Record a checkpoint every few commits so behind/diverged branches fork
+ // at many distinct depths rather than a handful of fixed points.
+ const CHECKPOINT_EVERY: usize = 5;
let repo = repo.to_path_buf();
std::fs::create_dir_all(&repo).unwrap();
@@ -603,21 +617,25 @@ pub fn create_mixed_repo_at(worktrees: usize, branches: usize, repo: &Path) {
);
run_git(&repo, &["add", "."]);
run_git(&repo, &["commit", "-q", "-m", &format!("Commit {c}")]);
- if c % 20 == 0 {
+ if c % CHECKPOINT_EVERY == 0 {
checkpoints.push(head_sha(&repo));
}
}
let base_tip = head_sha(&repo);
+ // `checkpoints[0]` is the oldest (initial commit); the last is near the
+ // tip. Index `i` of `branches` maps linearly across them, so behind/
+ // diverged branches fork at points fanned across history depth rather than
+ // a few repeated checkpoints.
+ let deepest = checkpoints.len() - 1;
// Branches without worktrees, in varied states. States 1 and 2 check out
// in the main worktree and return to main; the loop always ends on main.
for i in 0..branches {
let name = format!("br-{i:04}");
+ // `branches >= 1` inside this loop, so the divisor is never zero.
+ let fork = &checkpoints[i * deepest / branches];
match i % 4 {
- 0 => run_git(
- &repo,
- &["branch", &name, &checkpoints[i % checkpoints.len()]],
- ),
+ 0 => run_git(&repo, &["branch", &name, fork]),
1 => {
run_git(&repo, &["checkout", "-q", "-b", &name, &base_tip]);
for j in 0..=(i % 3) {
@@ -632,23 +650,19 @@ pub fn create_mixed_repo_at(worktrees: usize, branches: usize, repo: &Path) {
run_git(&repo, &["checkout", "-q", "main"]);
}
2 => {
- run_git(
- &repo,
- &[
- "checkout",
- "-q",
- "-b",
- &name,
- &checkpoints[i % checkpoints.len()],
- ],
- );
- std::fs::write(
- repo.join(format!("br_{i}_d.rs")),
- format!("// diverge {i}\n"),
- )
- .unwrap();
- run_git(&repo, &["add", "."]);
- run_git(&repo, &["commit", "-q", "-m", &format!("br {i} diverge")]);
+ run_git(&repo, &["checkout", "-q", "-b", &name, fork]);
+ for j in 0..=(i % 3) {
+ std::fs::write(
+ repo.join(format!("br_{i}_{j}_d.rs")),
+ format!("// diverge {i}/{j}\n"),
+ )
+ .unwrap();
+ run_git(&repo, &["add", "."]);
+ run_git(
+ &repo,
+ &["commit", "-q", "-m", &format!("br {i} diverge {j}")],
+ );
+ }
run_git(&repo, &["checkout", "-q", "main"]);
}
_ => run_git(&repo, &["branch", &name, &base_tip]),