Skip to content

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

bench: add time-to-first-output benchmarks for remove, switch, list (#1023)

Maximilian Roos447140fa5d25
diff --git a/Cargo.toml b/Cargo.toml
index 0a0604862..c3ce74b60 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -159,6 +159,10 @@ harness = false
name = "cow_copy"
harness = false
+[[bench]]
+name = "time_to_first_output"
+harness = false
+
[lints.rust]
unsafe_code = "forbid"
diff --git a/benches/CLAUDE.md b/benches/CLAUDE.md
index d52b0b95f..311e9a394 100644
--- a/benches/CLAUDE.md
+++ b/benches/CLAUDE.md
@@ -1,6 +1,6 @@
# Benchmark Guidelines
-See `list.rs` header for the authoritative list of benchmark groups and run examples.
+See `list.rs` and `time_to_first_output.rs` headers for benchmark groups and run examples.
## Quick Start
@@ -14,8 +14,12 @@ cargo bench --bench list many_branches
# GH #461 scenario (200 branches on rust-lang/rust)
cargo bench --bench list real_repo_many_branches
-# All benchmarks (~1 hour)
+# All list benchmarks (~1 hour)
cargo bench --bench list
+
+# Time-to-first-output benchmarks
+cargo bench --bench time_to_first_output # all commands
+cargo bench --bench time_to_first_output -- remove # just remove
```
## Rust Repo Caching
diff --git a/benches/list.rs b/benches/list.rs
index 2dce13ab6..579b473e6 100644
--- a/benches/list.rs
+++ b/benches/list.rs
@@ -24,7 +24,10 @@
use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main};
use std::path::{Path, PathBuf};
use std::process::Command;
-use wt_perf::{RepoConfig, create_repo, ensure_rust_repo, invalidate_caches, setup_fake_remote};
+use wt_perf::{
+ RepoConfig, add_history_spread_branches, add_worktrees, clone_rust_repo, create_repo,
+ invalidate_caches_auto, run_git, setup_fake_remote,
+};
/// Benchmark configuration wrapping RepoConfig with cache state.
#[derive(Clone)]
@@ -60,22 +63,6 @@ impl BenchConfig {
}
}
-fn run_git(path: &Path, args: &[&str]) {
- let output = Command::new("git")
- .args(args)
- .current_dir(path)
- .output()
- .unwrap();
- assert!(
- output.status.success(),
- "Git command failed: {:?}\nstderr: {}\nstdout: {}\npath: {}",
- args,
- String::from_utf8_lossy(&output.stderr),
- String::from_utf8_lossy(&output.stdout),
- path.display()
- );
-}
-
fn get_release_binary() -> &'static Path {
Path::new(env!("CARGO_BIN_EXE_wt"))
}
@@ -100,7 +87,7 @@ fn run_benchmark(
if config.cold_cache {
b.iter_batched(
- || invalidate_caches(repo_path, config.repo.worktrees),
+ || invalidate_caches_auto(repo_path),
|_| {
cmd_factory().output().unwrap();
},
@@ -204,73 +191,15 @@ fn bench_real_repo(c: &mut Criterion) {
BenchmarkId::new(label, worktrees),
&(worktrees, cold),
|b, &(worktrees, cold)| {
- let rust_repo = ensure_rust_repo();
+ let config = RepoConfig::typical(worktrees);
let temp = tempfile::tempdir().unwrap();
- let workspace_main = temp.path().join("repo");
-
- let clone_output = Command::new("git")
- .args([
- "clone",
- "--local",
- rust_repo.to_str().unwrap(),
- workspace_main.to_str().unwrap(),
- ])
- .output()
- .unwrap();
- assert!(
- clone_output.status.success(),
- "Failed to clone rust repo to workspace"
- );
-
- run_git(&workspace_main, &["config", "user.name", "Benchmark"]);
- run_git(&workspace_main, &["config", "user.email", "[email protected]"]);
-
- // Add worktrees manually (can't use create_repo for external repo)
- for wt_num in 1..worktrees {
- let branch = format!("feature-wt-{wt_num}");
- let wt_path = temp.path().join(format!("wt-{wt_num}"));
-
- let head_output = Command::new("git")
- .args(["rev-parse", "HEAD"])
- .current_dir(&workspace_main)
- .output()
- .unwrap();
- let base_commit = String::from_utf8_lossy(&head_output.stdout)
- .trim()
- .to_string();
-
- run_git(
- &workspace_main,
- &[
- "worktree",
- "add",
- "-b",
- &branch,
- wt_path.to_str().unwrap(),
- &base_commit,
- ],
- );
-
- for i in 0..10 {
- let file_path = wt_path.join(format!("feature_{wt_num}_file_{i}.txt"));
- std::fs::write(&file_path, format!("Feature {wt_num} content {i}\n"))
- .unwrap();
- run_git(&wt_path, &["add", "."]);
- run_git(
- &wt_path,
- &["commit", "-m", &format!("Feature {wt_num} commit {i}")],
- );
- }
-
- for i in 0..3 {
- let file_path = wt_path.join(format!("uncommitted_{i}.txt"));
- std::fs::write(&file_path, "Uncommitted content\n").unwrap();
- }
- }
+ let workspace_main = clone_rust_repo(&temp);
+ add_worktrees(&config, &workspace_main);
+ run_git(&workspace_main, &["status"]);
if cold {
b.iter_batched(
- || invalidate_caches(&workspace_main, worktrees),
+ || invalidate_caches_auto(&workspace_main),
|_| {
Command::new(binary)
.arg("list")
@@ -281,7 +210,6 @@ fn bench_real_repo(c: &mut Criterion) {
criterion::BatchSize::SmallInput,
);
} else {
- run_git(&workspace_main, &["status"]);
b.iter(|| {
Command::new(binary)
.arg("list")
@@ -351,46 +279,12 @@ fn bench_divergent_branches(c: &mut Criterion) {
group.finish();
}
-/// Helper to set up rust repo workspace with branches at different history depths.
+/// Set up rust repo workspace with branches at different history depths.
/// Returns the workspace path (temp dir must outlive usage).
fn setup_rust_workspace_with_branches(temp: &tempfile::TempDir, num_branches: usize) -> PathBuf {
- let rust_repo = ensure_rust_repo();
- let workspace_main = temp.path().join("repo");
-
- // Clone rust repo locally
- let clone_output = Command::new("git")
- .args([
- "clone",
- "--local",
- rust_repo.to_str().unwrap(),
- workspace_main.to_str().unwrap(),
- ])
- .output()
- .unwrap();
- assert!(
- clone_output.status.success(),
- "Failed to clone rust repo to workspace"
- );
-
- // Get commits spread across history
- let log_output = Command::new("git")
- .args(["log", "--oneline", "-n", "5000", "--format=%H"])
- .current_dir(&workspace_main)
- .output()
- .unwrap();
- let log_str = String::from_utf8_lossy(&log_output.stdout);
- let step = 5000 / num_branches;
- let commits: Vec<&str> = log_str.lines().step_by(step).take(num_branches).collect();
-
- // Create branches pointing to different historical commits
- for (i, commit) in commits.iter().enumerate() {
- let branch_name = format!("feature-{i:03}");
- run_git(&workspace_main, &["branch", &branch_name, commit]);
- }
-
- // Warm the cache
+ let workspace_main = clone_rust_repo(temp);
+ add_history_spread_branches(&workspace_main, num_branches);
run_git(&workspace_main, &["status"]);
-
workspace_main
}
diff --git a/benches/time_to_first_output.rs b/benches/time_to_first_output.rs
new file mode 100644
index 000000000..8b3a2a242
--- /dev/null
+++ b/benches/time_to_first_output.rs
@@ -0,0 +1,92 @@
+// Benchmarks for time-to-first-output across wt commands
+//
+// Measures how long each command takes before showing any user-visible output.
+// Uses WORKTRUNK_FIRST_OUTPUT env var to exit at the point of first output.
+//
+// Benchmark variants:
+// - first_output/remove
+// - first_output/switch
+// - first_output/list
+//
+// Run examples:
+// cargo bench --bench time_to_first_output # All commands
+// cargo bench --bench time_to_first_output -- remove # Just remove
+// cargo bench --bench time_to_first_output -- switch # Just switch
+
+use criterion::{Criterion, criterion_group, criterion_main};
+use std::path::Path;
+use std::process::Command;
+use wt_perf::{RepoConfig, create_repo, setup_fake_remote};
+
+fn get_release_binary() -> &'static Path {
+ Path::new(env!("CARGO_BIN_EXE_wt"))
+}
+
+/// Run a command and assert it succeeded.
+fn run_bench_cmd(cmd: &mut Command) {
+ let output = cmd.output().unwrap();
+ assert!(
+ output.status.success(),
+ "Benchmark command failed:\nstderr: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+}
+
+fn bench_first_output(c: &mut Criterion) {
+ let mut group = c.benchmark_group("first_output");
+ let binary = get_release_binary();
+ let env = ("WORKTRUNK_FIRST_OUTPUT", "1");
+
+ let config = RepoConfig::typical(4);
+ let temp = create_repo(&config);
+ let repo_path = temp.path().join("repo");
+ setup_fake_remote(&repo_path);
+
+ // remove: exits after validation, before approval/output
+ group.bench_function("remove", |b| {
+ b.iter(|| {
+ run_bench_cmd(
+ Command::new(binary)
+ .args(["remove", "--yes", "--no-verify", "--force", "feature-wt-1"])
+ .current_dir(&repo_path)
+ .env(env.0, env.1),
+ );
+ });
+ });
+
+ // switch: exits after execute_switch, before output
+ group.bench_function("switch", |b| {
+ b.iter(|| {
+ run_bench_cmd(
+ Command::new(binary)
+ .args(["switch", "--yes", "--no-verify", "feature-wt-1"])
+ .current_dir(&repo_path)
+ .env(env.0, env.1),
+ );
+ });
+ });
+
+ // list: exits after skeleton data collection, before render
+ group.bench_function("list", |b| {
+ b.iter(|| {
+ run_bench_cmd(
+ Command::new(binary)
+ .arg("list")
+ .current_dir(&repo_path)
+ .env(env.0, env.1),
+ );
+ });
+ });
+
+ group.finish();
+}
+
+criterion_group! {
+ name = benches;
+ config = Criterion::default()
+ .sample_size(30)
+ .measurement_time(std::time::Duration::from_secs(15))
+ .warm_up_time(std::time::Duration::from_secs(3));
+ targets = bench_first_output
+}
+criterion_main!(benches);
diff --git a/src/commands/handle_switch.rs b/src/commands/handle_switch.rs
index ab955afaa..de140738e 100644
--- a/src/commands/handle_switch.rs
+++ b/src/commands/handle_switch.rs
@@ -156,6 +156,11 @@ pub fn handle_switch(
// Execute the validated plan
let (result, branch_info) = execute_switch(&repo, plan, config, yes, skip_hooks)?;
+ // Early exit for benchmarking time-to-first-output
+ if std::env::var_os("WORKTRUNK_FIRST_OUTPUT").is_some() {
+ return Ok(());
+ }
+
// Show success message (temporal locality: immediately after worktree operation)
// Returns path to display in hooks when user's shell won't be in the worktree
// Also shows worktree-path hint on first --create (before shell integration warning)
diff --git a/src/commands/list/collect/mod.rs b/src/commands/list/collect/mod.rs
index e761d77bc..96dc09a84 100644
--- a/src/commands/list/collect/mod.rs
+++ b/src/commands/list/collect/mod.rs
@@ -502,8 +502,10 @@ pub fn collect(
None
};
- // Early exit for benchmarking skeleton render time
- if std::env::var("WORKTRUNK_SKELETON_ONLY").is_ok() {
+ // Early exit for benchmarking skeleton render time / time-to-first-output
+ if std::env::var_os("WORKTRUNK_SKELETON_ONLY").is_some()
+ || std::env::var_os("WORKTRUNK_FIRST_OUTPUT").is_some()
+ {
return Ok(None);
}
diff --git a/src/main.rs b/src/main.rs
index 7d9ea1d75..f0a5a8bad 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -853,6 +853,11 @@ fn main() {
handle_remove_current(!delete_branch, force_delete, force, &config)
.context("Failed to remove worktree")?;
+ // Early exit for benchmarking time-to-first-output
+ if std::env::var_os("WORKTRUNK_FIRST_OUTPUT").is_some() {
+ return Ok(());
+ }
+
// "Approve at the Gate": approval happens AFTER validation passes
let run_hooks = verify && approve_remove(yes)?;
@@ -962,6 +967,11 @@ fn main() {
anyhow::bail!("");
}
+ // Early exit for benchmarking time-to-first-output
+ if std::env::var_os("WORKTRUNK_FIRST_OUTPUT").is_some() {
+ return Ok(());
+ }
+
// Phase 2: Approve hooks (only if we have valid plans)
// TODO(pre-remove-context): Approval context uses current worktree,
// but hooks execute in each target worktree.
diff --git a/tests/helpers/wt-perf/src/lib.rs b/tests/helpers/wt-perf/src/lib.rs
index 8a47d7559..6aab2fdc9 100644
--- a/tests/helpers/wt-perf/src/lib.rs
+++ b/tests/helpers/wt-perf/src/lib.rs
@@ -1,21 +1,21 @@
//! Performance testing and tracing tools for worktrunk.
//!
//! This crate provides:
-//! - Benchmark repository setup (used by `benches/list.rs`)
+//! - Benchmark repository setup (used by `benches/list.rs`, `benches/time_to_first_output.rs`)
//! - Cache invalidation for cold benchmark runs
//! - Trace analysis utilities
//!
//! # Library Usage
//!
//! ```rust,ignore
-//! use wt_perf::{RepoConfig, create_repo, invalidate_caches};
+//! use wt_perf::{RepoConfig, create_repo, invalidate_caches_auto};
//!
//! // Create a test repo with 8 worktrees
//! let temp = create_repo(&RepoConfig::typical(8));
//! let repo_path = temp.path().join("main");
//!
//! // Invalidate caches for cold benchmark
-//! invalidate_caches(&repo_path, 8);
+//! invalidate_caches_auto(&repo_path);
//! ```
//!
//! # CLI Usage
@@ -115,7 +115,7 @@ impl RepoConfig {
}
/// Run a git command in the given directory.
-fn run_git(path: &Path, args: &[&str]) {
+pub fn run_git(path: &Path, args: &[&str]) {
let output = Command::new("git")
.args(args)
.current_dir(path)
@@ -218,16 +218,28 @@ pub fn create_repo_at(config: &RepoConfig, base_path: &Path) {
run_git(&repo_path, &["checkout", "main"]);
}
- // Add worktrees (siblings with .branch suffix, worktrunk convention)
- let repo_name = base_path.file_name().unwrap().to_str().unwrap();
- let parent_dir = base_path.parent().unwrap();
+ add_worktrees(config, &repo_path);
+
+ // Set up fake remote for default branch detection
+ setup_fake_remote(&repo_path);
+}
+
+/// Add worktrees to an existing repo using worktrunk naming convention.
+///
+/// Creates `config.worktrees - 1` linked worktrees as siblings of `repo_path`
+/// (e.g., `repo.feature-wt-1`), each with diverging commits and uncommitted files
+/// controlled by `config.worktree_commits_ahead` and `config.worktree_uncommitted_files`.
+pub fn add_worktrees(config: &RepoConfig, repo_path: &Path) {
+ let repo_name = repo_path.file_name().unwrap().to_str().unwrap();
+ let parent_dir = repo_path.parent().unwrap();
+
for wt_num in 1..config.worktrees {
let branch = format!("feature-wt-{wt_num}");
let wt_path = parent_dir.join(format!("{repo_name}.{branch}"));
let head_output = Command::new("git")
.args(["rev-parse", "HEAD"])
- .current_dir(&repo_path)
+ .current_dir(repo_path)
.output()
.unwrap();
let base_commit = String::from_utf8_lossy(&head_output.stdout)
@@ -235,7 +247,7 @@ pub fn create_repo_at(config: &RepoConfig, base_path: &Path) {
.to_string();
run_git(
- &repo_path,
+ repo_path,
&[
"worktree",
"add",
@@ -246,7 +258,6 @@ pub fn create_repo_at(config: &RepoConfig, base_path: &Path) {
],
);
- // Add diverging commits
for i in 0..config.worktree_commits_ahead {
let file_path = wt_path.join(format!("feature_{wt_num}_file_{i}.txt"));
std::fs::write(&file_path, format!("Feature {wt_num} content {i}\n")).unwrap();
@@ -257,15 +268,11 @@ pub fn create_repo_at(config: &RepoConfig, base_path: &Path) {
);
}
- // Add uncommitted changes
for i in 0..config.worktree_uncommitted_files {
let file_path = wt_path.join(format!("uncommitted_{i}.txt"));
std::fs::write(&file_path, "Uncommitted content\n").unwrap();
}
}
-
- // Set up fake remote for default branch detection
- setup_fake_remote(&repo_path);
}
/// Set up a fake remote for default branch detection.
@@ -281,34 +288,6 @@ pub fn setup_fake_remote(repo_path: &Path) {
std::fs::write(refs_dir.join("main"), head_sha.stdout).unwrap();
}
-/// Invalidate git caches for cold benchmarks.
-///
-/// Removes:
-/// - Index files (main + worktrees)
-/// - Commit graph
-/// - Packed refs
-pub fn invalidate_caches(repo_path: &Path, num_worktrees: usize) {
- let git_dir = repo_path.join(".git");
-
- // Remove index files
- let _ = std::fs::remove_file(git_dir.join("index"));
- for i in 1..num_worktrees {
- let _ = std::fs::remove_file(
- git_dir
- .join("worktrees")
- .join(format!("wt-{i}"))
- .join("index"),
- );
- }
-
- // Remove commit graph
- let _ = std::fs::remove_file(git_dir.join("objects/info/commit-graph"));
- let _ = std::fs::remove_dir_all(git_dir.join("objects/info/commit-graphs"));
-
- // Remove packed refs
- let _ = std::fs::remove_file(git_dir.join("packed-refs"));
-}
-
/// Invalidate caches for any repo (auto-detects worktrees).
pub fn invalidate_caches_auto(repo_path: &Path) {
let git_dir = repo_path.join(".git");
@@ -377,6 +356,55 @@ pub fn ensure_rust_repo() -> PathBuf {
.clone()
}
+/// Clone rust-lang/rust into `temp/repo` for benchmarking.
+///
+/// Returns the clone path. Configures git user for commits.
+/// The `temp` dir must outlive usage.
+pub fn clone_rust_repo(temp: &TempDir) -> PathBuf {
+ let rust_repo = ensure_rust_repo();
+ let workspace_main = temp.path().join("repo");
+
+ let clone_output = Command::new("git")
+ .args([
+ "clone",
+ "--local",
+ rust_repo.to_str().unwrap(),
+ workspace_main.to_str().unwrap(),
+ ])
+ .output()
+ .unwrap();
+ assert!(
+ clone_output.status.success(),
+ "Failed to clone rust repo to workspace"
+ );
+
+ run_git(&workspace_main, &["config", "user.name", "Benchmark"]);
+ run_git(&workspace_main, &["config", "user.email", "[email protected]"]);
+
+ workspace_main
+}
+
+/// Create branches pointing at different depths in the repo's commit history.
+///
+/// Samples `count` commits evenly spread across the last 5000 commits and
+/// creates `feature-NNN` branches pointing at them. This reproduces the
+/// GH #461 scenario where branch divergence depth (not count) drives cost.
+pub fn add_history_spread_branches(repo_path: &Path, count: usize) {
+ let log_output = Command::new("git")
+ .args(["log", "--oneline", "-n", "5000", "--format=%H"])
+ .current_dir(repo_path)
+ .output()
+ .unwrap();
+ let log_str = String::from_utf8_lossy(&log_output.stdout);
+ let step = 5000 / count;
+ let commits: Vec<&str> = log_str.lines().step_by(step).take(count).collect();
+
+ for (i, commit) in commits.iter().enumerate() {
+ let branch_name = format!("feature-{i:03}");
+ run_git(repo_path, &["branch", &branch_name, commit]);
+ }
+}
+
/// Canonicalize path without Windows `\\?\` prefix.
pub fn canonicalize(path: &Path) -> std::io::Result<PathBuf> {
dunce::canonicalize(path)