Skip to content

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

feat: Add `time_to_skeleton` and `time_to_complete` benchmarks

Maximilian Roosdc3d36a116ad
diff --git a/benches/CLAUDE.md b/benches/CLAUDE.md
index b391bf690..30d2689c8 100644
--- a/benches/CLAUDE.md
+++ b/benches/CLAUDE.md
@@ -18,6 +18,10 @@ cargo bench --bench list bench_list_real_repo
## Benchmark Types
### 1. Synthetic Benchmarks (Fast, ~5-10 minutes)
+- `bench_time_to_skeleton` - Time until skeleton appears (progressive mode, warm caches)
+- `bench_time_to_skeleton_cold` - Same as above but with packed-refs invalidated
+- `bench_time_to_complete` - Full `wt list` execution (all data filled in), warm caches
+- `bench_time_to_complete_cold` - Same as above but with packed-refs invalidated
- `bench_list_by_worktree_count` - Scaling with worktree count (1-8), warm caches
- `bench_list_by_repo_profile` - Scaling with repo size (minimal/typical/large), warm caches
- `bench_list_sequential_vs_parallel` - Sequential vs parallel comparison
diff --git a/benches/list.rs b/benches/list.rs
index 7741dcbb6..e67aeab2a 100644
--- a/benches/list.rs
+++ b/benches/list.rs
@@ -3,6 +3,10 @@
// This suite measures raw performance and scaling characteristics:
//
// 1. Synthetic benchmarks (fast, deterministic):
+// - bench_time_to_skeleton: Measures time until skeleton appears (progressive mode)
+// - bench_time_to_skeleton_cold: Same as above but with packed-refs invalidated
+// - bench_time_to_complete: Measures full `wt list` execution (when all data appears), warm caches
+// - bench_time_to_complete_cold: Same as above but with packed-refs invalidated
// - bench_list_by_worktree_count: Measures scaling with worktree count (1-8), warm caches
// - bench_list_by_repo_profile: Measures scaling with repo size (minimal/typical/large), warm caches
// - bench_sequential_vs_parallel: Light comparison of sequential vs parallel (3 data points), warm caches
@@ -17,6 +21,7 @@
// cargo bench --bench list
//
// Run specific benchmark:
+// cargo bench --bench list bench_time_to_skeleton
// cargo bench --bench list bench_list_by_worktree_count
// cargo bench --bench list bench_list_cold_cache
// cargo bench --bench list bench_list_real_repo
@@ -249,6 +254,242 @@ fn add_worktree_with_divergence(
}
}
+/// Benchmark time to render skeleton (before cell filling starts).
+///
+/// Uses WT_SKELETON_ONLY=1 to exit after skeleton is rendered.
+/// This measures the actual worktrunk code path: git I/O, parsing, layout, render skeleton.
+fn bench_time_to_skeleton(c: &mut Criterion) {
+ let mut group = c.benchmark_group("time_to_skeleton");
+
+ let binary = get_release_binary();
+ let profile = &PROFILES[1];
+
+ for num_worktrees in [1, 4, 8] {
+ let temp = create_realistic_repo(profile.commits, profile.files);
+ let repo_path = temp.path().join("main");
+
+ for i in 1..num_worktrees {
+ add_worktree_with_divergence(
+ &temp,
+ &repo_path,
+ i,
+ profile.commits_ahead,
+ profile.commits_behind,
+ profile.uncommitted_files,
+ );
+ }
+
+ // Set up cached default branch
+ let refs_dir = repo_path.join(".git/refs/remotes/origin");
+ std::fs::create_dir_all(&refs_dir).unwrap();
+ std::fs::write(refs_dir.join("HEAD"), "ref: refs/remotes/origin/main\n").unwrap();
+ let head_sha = Command::new("git")
+ .args(["rev-parse", "HEAD"])
+ .current_dir(&repo_path)
+ .output()
+ .unwrap();
+ std::fs::write(refs_dir.join("main"), head_sha.stdout).unwrap();
+
+ group.bench_with_input(
+ BenchmarkId::from_parameter(num_worktrees),
+ &num_worktrees,
+ |b, _| {
+ b.iter(|| {
+ Command::new(&binary)
+ .arg("list")
+ .env("WT_SKELETON_ONLY", "1")
+ .current_dir(&repo_path)
+ .output()
+ .unwrap();
+ });
+ },
+ );
+ }
+
+ group.finish();
+}
+
+/// Cold cache variant of time_to_skeleton benchmark.
+/// Invalidates packed-refs before each measurement.
+fn bench_time_to_skeleton_cold(c: &mut Criterion) {
+ let mut group = c.benchmark_group("time_to_skeleton_cold");
+
+ let binary = get_release_binary();
+ let profile = &PROFILES[1];
+
+ for num_worktrees in [1, 4, 8] {
+ let temp = create_realistic_repo(profile.commits, profile.files);
+ let repo_path = temp.path().join("main");
+
+ for i in 1..num_worktrees {
+ add_worktree_with_divergence(
+ &temp,
+ &repo_path,
+ i,
+ profile.commits_ahead,
+ profile.commits_behind,
+ profile.uncommitted_files,
+ );
+ }
+
+ // Set up cached default branch
+ let refs_dir = repo_path.join(".git/refs/remotes/origin");
+ std::fs::create_dir_all(&refs_dir).unwrap();
+ std::fs::write(refs_dir.join("HEAD"), "ref: refs/remotes/origin/main\n").unwrap();
+ let head_sha = Command::new("git")
+ .args(["rev-parse", "HEAD"])
+ .current_dir(&repo_path)
+ .output()
+ .unwrap();
+ std::fs::write(refs_dir.join("main"), head_sha.stdout).unwrap();
+
+ let packed_refs = repo_path.join(".git/packed-refs");
+
+ group.bench_with_input(
+ BenchmarkId::from_parameter(num_worktrees),
+ &num_worktrees,
+ |b, _| {
+ b.iter_batched(
+ || {
+ // Invalidate packed-refs before each iteration
+ if packed_refs.exists() {
+ std::fs::remove_file(&packed_refs).unwrap();
+ }
+ },
+ |_| {
+ Command::new(&binary)
+ .arg("list")
+ .env("WT_SKELETON_ONLY", "1")
+ .current_dir(&repo_path)
+ .output()
+ .unwrap();
+ },
+ criterion::BatchSize::SmallInput,
+ );
+ },
+ );
+ }
+
+ group.finish();
+}
+
+/// Benchmark `wt list` full execution time with warm caches.
+///
+/// This measures the actual worktrunk code path including git operations, parsing,
+/// layout calculation, and rendering - i.e., when all data is filled in.
+fn bench_time_to_complete(c: &mut Criterion) {
+ let mut group = c.benchmark_group("time_to_complete");
+
+ let binary = get_release_binary();
+ let profile = &PROFILES[1];
+
+ for num_worktrees in [1, 4, 8] {
+ let temp = create_realistic_repo(profile.commits, profile.files);
+ let repo_path = temp.path().join("main");
+
+ for i in 1..num_worktrees {
+ add_worktree_with_divergence(
+ &temp,
+ &repo_path,
+ i,
+ profile.commits_ahead,
+ profile.commits_behind,
+ profile.uncommitted_files,
+ );
+ }
+
+ // Set up cached default branch
+ let refs_dir = repo_path.join(".git/refs/remotes/origin");
+ std::fs::create_dir_all(&refs_dir).unwrap();
+ std::fs::write(refs_dir.join("HEAD"), "ref: refs/remotes/origin/main\n").unwrap();
+ let head_sha = Command::new("git")
+ .args(["rev-parse", "HEAD"])
+ .current_dir(&repo_path)
+ .output()
+ .unwrap();
+ std::fs::write(refs_dir.join("main"), head_sha.stdout).unwrap();
+
+ group.bench_with_input(
+ BenchmarkId::from_parameter(num_worktrees),
+ &num_worktrees,
+ |b, _| {
+ b.iter(|| {
+ Command::new(&binary)
+ .arg("list")
+ .current_dir(&repo_path)
+ .output()
+ .unwrap();
+ });
+ },
+ );
+ }
+
+ group.finish();
+}
+
+/// Cold cache variant of time_to_complete benchmark.
+/// Invalidates packed-refs before each measurement.
+fn bench_time_to_complete_cold(c: &mut Criterion) {
+ let mut group = c.benchmark_group("time_to_complete_cold");
+
+ let binary = get_release_binary();
+ let profile = &PROFILES[1];
+
+ for num_worktrees in [1, 4, 8] {
+ let temp = create_realistic_repo(profile.commits, profile.files);
+ let repo_path = temp.path().join("main");
+
+ for i in 1..num_worktrees {
+ add_worktree_with_divergence(
+ &temp,
+ &repo_path,
+ i,
+ profile.commits_ahead,
+ profile.commits_behind,
+ profile.uncommitted_files,
+ );
+ }
+
+ // Set up cached default branch
+ let refs_dir = repo_path.join(".git/refs/remotes/origin");
+ std::fs::create_dir_all(&refs_dir).unwrap();
+ std::fs::write(refs_dir.join("HEAD"), "ref: refs/remotes/origin/main\n").unwrap();
+ let head_sha = Command::new("git")
+ .args(["rev-parse", "HEAD"])
+ .current_dir(&repo_path)
+ .output()
+ .unwrap();
+ std::fs::write(refs_dir.join("main"), head_sha.stdout).unwrap();
+
+ let packed_refs = repo_path.join(".git/packed-refs");
+
+ group.bench_with_input(
+ BenchmarkId::from_parameter(num_worktrees),
+ &num_worktrees,
+ |b, _| {
+ b.iter_batched(
+ || {
+ // Invalidate packed-refs before each iteration
+ if packed_refs.exists() {
+ std::fs::remove_file(&packed_refs).unwrap();
+ }
+ },
+ |_| {
+ Command::new(&binary)
+ .arg("list")
+ .current_dir(&repo_path)
+ .output()
+ .unwrap();
+ },
+ criterion::BatchSize::SmallInput,
+ );
+ },
+ );
+ }
+
+ group.finish();
+}
+
fn bench_list_by_worktree_count(c: &mut Criterion) {
let mut group = c.benchmark_group("list_by_worktree_count");
@@ -750,6 +991,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_list_by_worktree_count, bench_list_by_repo_profile, bench_sequential_vs_parallel, bench_list_cold_cache, bench_list_real_repo, bench_list_real_repo_cold_cache
+ targets = bench_time_to_skeleton, bench_time_to_skeleton_cold, bench_time_to_complete, bench_time_to_complete_cold, bench_list_by_worktree_count, bench_list_by_repo_profile, bench_sequential_vs_parallel, bench_list_cold_cache, bench_list_real_repo, bench_list_real_repo_cold_cache
}
criterion_main!(benches);
diff --git a/src/commands/list/collect.rs b/src/commands/list/collect.rs
index 2fd24592b..4a678b371 100644
--- a/src/commands/list/collect.rs
+++ b/src/commands/list/collect.rs
@@ -648,6 +648,11 @@ pub fn collect(
None
};
+ // Early exit for benchmarking skeleton render time
+ if std::env::var("WT_SKELETON_ONLY").is_ok() {
+ return Ok(None);
+ }
+
// Cache last rendered (unclamped) message per row to avoid redundant updates.
let mut last_rendered_lines: Vec<String> = vec![String::new(); all_items.len()];
diff --git a/src/commands/list/mod.rs b/src/commands/list/mod.rs
index 0d3b9e1de..71059966e 100644
--- a/src/commands/list/mod.rs
+++ b/src/commands/list/mod.rs
@@ -5,6 +5,48 @@
//! `wt list` runs multiple git commands per worktree in parallel using Rayon. Performance
//! depends heavily on git's internal caches, not worktrunk-specific caching.
//!
+//! ## Time to First Information
+//!
+//! Before displaying actual data, we perform these sequential operations:
+//!
+//! 1. **`git worktree list --porcelain`** (~5-15ms)
+//! - Lists all worktrees with their paths, HEADs, and branches
+//! - Uses ref cache, very fast
+//!
+//! 2. **Default branch lookup** (~1-5ms)
+//! - Reads cached value from `.git/refs/remotes/origin/HEAD`
+//! - Falls back to `git remote show origin` if not cached (~100-300ms network)
+//! - Refresh with `wt config refresh-cache`
+//!
+//! 3. **Sort worktrees** (<1ms)
+//! - Orders by: current → main → rest alphabetically
+//! - Pure Rust, no git calls
+//!
+//! 4. **Branch listing** (only with `--branches`, ~10-30ms)
+//! - `git for-each-ref refs/heads` - lists local branches
+//! - Filters out branches that already have worktrees
+//!
+//! 5. **Remote branch listing** (only with `--remotes`, ~10-50ms)
+//! - `git for-each-ref refs/remotes` - lists remote branches
+//! - Scales with number of remotes/branches
+//!
+//! 6. **Layout calculation** (<1ms)
+//! - Determines column widths from branch names and paths
+//! - Pure Rust, no git calls
+//!
+//! **Time to skeleton: ~50ms** (placeholder rows with loading indicators)
+//!
+//! Skeleton timing is stable at ~46-52ms regardless of worktree count (1-8) or cache state.
+//! This is because skeleton operations (worktree list, default branch lookup, layout) use
+//! git's ref cache rather than packed-refs or the index.
+//!
+//! **Time to complete: ~60-170ms** (all data filled in, depends on worktree count)
+//!
+//! First run in a repo without cached default branch adds ~100-300ms for network lookup.
+//!
+//! After the skeleton appears, cells fill in progressively as git operations complete.
+//! The slowest operations (CI status, merge-tree conflict detection) only run with `--full`.
+//!
//! ## Git Commands Per Worktree
//!
//! For each worktree, we execute: