Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(perf): add picker/collect phase timings and trace instrumentation (#2250)
Maximilian Roos16d2d6e5f99e
diff --git a/src/commands/list/collect/mod.rs b/src/commands/list/collect/mod.rsindex dfd1d48c4..abd978c62 100644--- a/src/commands/list/collect/mod.rs+++ b/src/commands/list/collect/mod.rs@@ -74,6 +74,36 @@//! When adding new features, ask: "Can this be computed after skeleton?" If yes, defer it.//! The skeleton shows `·` placeholder for gutter symbols, filled in when data loads.//!+//! ### Measured Phase Timings+//!+//! Representative medians on the worktrunk dev repo (7 worktrees, 6+//! branches, warm caches, release build, `--progressive` forced so the+//! progressive-table path fires even with stdout piped).+//!+//! | Phase | median | cmds |+//! |-------|-------:|-----:|+//! | `List collect started → Skeleton rendered` (pre-skeleton) | ~60ms | 23 |+//! | `Skeleton rendered → Spawning worker thread` (rayon::scope + work-item setup) | ~41ms | 7 |+//! | `Spawning worker thread → Parallel execution started` | <100µs | 0 |+//! | `Parallel execution started → First result received` | <100µs | 0 |+//! | `First result received → All results drained` (parallel work) | ~436ms | 154 |+//! | `All results drained → List collect complete` (final render) | ~344µs | 0 |+//! | Wall clock | ~549ms | — |+//!+//! The 23-command pre-skeleton count is above the "6-8 commands" target+//! above — worth an audit. Most of the extras come from per-worktree probes+//! that creep into the phase.+//!+//! Reproduce end-to-end via+//! `cargo bench --bench time_to_first_output -- list`; for a per-phase+//! breakdown, capture a trace and run the phase-duration SQL query from+//! `benches/CLAUDE.md`:+//!+//! ```bash+//! RUST_LOG=debug ./target/release/wt -C <repo> list --progressive \+//! 2> >(cargo run -p wt-perf --release -q -- trace > trace.json)+//! ```+//!//! ## Unified Collection Architecture//!//! Progressive and buffered modes use the same collection and rendering code.@@ -869,6 +899,9 @@ pub fn collect(.map(|item| layout.render_skeleton_row(item).render()).collect();handler.on_skeleton(all_items.clone(), skeletons, layout.render_header_line());+ // Mirror the `wt list` progressive-table marker so `wt-perf phases`+ // sees the same boundary across both commands.+ worktrunk::shell_exec::trace_instant("Skeleton rendered");}/// Delay before the `·` loading indicator replaces blank placeholders.diff --git a/src/commands/picker/mod.rs b/src/commands/picker/mod.rsindex 98a5d392f..391051aa0 100644--- a/src/commands/picker/mod.rs+++ b/src/commands/picker/mod.rs@@ -1,6 +1,88 @@//! Interactive branch/worktree selector.//!-//! A skim-based TUI for selecting and switching between worktrees.+//! A skim-based TUI for selecting and switching between worktrees. The picker+//! shares `super::list::collect::collect` with `wt list` — see+//! `commands/list/collect/mod.rs` for the rendering-pipeline spec — but inverts+//! the ordering because skim's `preview_window` height is baked into+//! `SkimOptions` before `Skim::run_with` takes over the terminal, so we have+//! to estimate the visible row count up front rather than learn it from+//! collect's skeleton pass.+//!+//! # "Skeleton"+//!+//! Same meaning as in `wt list`: the column/row frame with placeholder cells+//! the user sees first. In the picker, `collect::collect` builds those rows+//! and streams them via `on_skeleton` → `PickerHandler` → `SkimItemSender` →+//! skim. (Not to be confused with the rendered skeleton-row *strings* that+//! flow through that channel.)+//!+//! # Startup flow+//!+//! On the main thread, `handle_picker`:+//!+//! 1. `current_or_recover` + config resolution.+//! 2. `PreviewState::new` — auto-detects Right vs Down layout.+//! 3. Allocates the `PreviewOrchestrator` and kicks off a *speculative*+//! `git diff HEAD` for the current worktree on the preview pool. That bg+//! work overlaps with everything below.+//! 4. Computes `num_items_estimate` — `list_worktrees` plus (conditionally)+//! `list_local_branches` / `list_remote_branches`, capped at+//! `MAX_VISIBLE_ITEMS`. Only used to size skim's `preview_window`.+//! 5. Builds `SkimOptions` (immutable after this — which is why steps 1-4 have+//! to run first).+//! 6. Spawns the `picker-collect` bg thread, which calls `collect::collect`.+//! 7. Calls `Skim::run_with(rx)`; skim paints the empty frame and then ingests+//! skeleton rows from the channel as the bg thread streams them via+//! `on_skeleton`.+//!+//! Time-to-skeleton = steps 1-6 on the main thread *plus* collect's+//! pre-skeleton phase on the bg thread.+//!+//! ## Phase timings+//!+//! Representative medians on the worktrunk dev repo (7 worktrees, 6 branches,+//! warm caches, release build).+//!+//! | Phase (instant-to-instant) | median | cmds |+//! |-----------------------------|-------:|-----:|+//! | `Picker started → Picker config resolved` | ~16ms | 3 |+//! | `Picker config resolved → Picker layout detected` | <1ms | 0 |+//! | `Picker layout detected → Picker estimate computed` | ~39ms | 11 (includes bg preview `git diff`s) |+//! | `Picker estimate computed → Picker skim options built` | <1ms | 0 |+//! | `Picker skim options built → Picker collect spawned` | <100µs | 0 |+//! | `Picker collect spawned → List collect started` | <100µs | 0 |+//! | `List collect started → Skeleton rendered` (bg, pre-skeleton) | ~41ms | 25 |+//! | **Time-to-skeleton** (≈ main-thread prelude + bg pre-skeleton) | **~96ms** | |+//! | `Skeleton rendered → Spawning worker thread` (post-skeleton, pre-work) | ~156ms | 86 |+//! | `Parallel execution started → All results drained` (post-skeleton work) | ~1.1s | 254 |+//! | Wall clock under `WORKTRUNK_PICKER_DRY_RUN=1` (median / p95) | ~1.4s / ~4.4s | |+//!+//! Skim's own paint cost isn't observable from the dry-run path — skim is+//! bypassed there.+//!+//! ### Reproducing+//!+//! End-to-end time-to-first-output (criterion, synthetic repo):+//!+//! ```bash+//! cargo bench --bench time_to_first_output -- switch+//! ```+//!+//! Per-phase breakdown on a specific repo (a single trace is usually enough+//! to spot where time goes; re-run a few times if you want variance):+//!+//! ```bash+//! RUST_LOG=debug ./target/release/wt -C <repo> switch \+//! 2> >(cargo run -p wt-perf --release -q -- trace > trace.json)+//! # Open trace.json in Perfetto, or run the phase-duration SQL query+//! # documented in benches/CLAUDE.md §"What's on the critical path?".+//! ```+//!+//! # TODO(picker-perf): dedupe git calls+//!+//! `num_items_estimate` and `collect::collect` each call `list_worktrees` and+//! `list_local_branches`. Pre-seed collect's OnceCells from the main-thread+//! fetch to save one of each on the bg thread's critical path toward skeleton.mod items;mod log_formatter;@@ -292,6 +374,7 @@ pub fn handle_picker(if std::env::var_os("WORKTRUNK_PICKER_DRY_RUN").is_none() && !std::io::stdin().is_terminal() {anyhow::bail!("Interactive picker requires an interactive terminal");}+ worktrunk::shell_exec::trace_instant("Picker started");let (repo, is_recovered) = current_or_recover()?;@@ -300,9 +383,11 @@ pub fn handle_picker(let change_dir = change_dir_flag.unwrap_or_else(|| config.switch.cd());let show_branches = cli_branches || config.list.branches();let show_remotes = cli_remotes || config.list.remotes();+ worktrunk::shell_exec::trace_instant("Picker config resolved");// Initialize preview mode state file (auto-cleanup on drop)let state = PreviewState::new();+ worktrunk::shell_exec::trace_instant("Picker layout detected");// Preview cache + dedicated pool are created up-front so the speculative// first-item preview can run in parallel with `collect::collect` below.@@ -378,6 +463,7 @@ pub fn handle_picker(}estimate};+ worktrunk::shell_exec::trace_instant("Picker estimate computed");let preview_window_spec = state.initial_layout.to_preview_window_spec(num_items_estimate);@@ -502,6 +588,7 @@ pub fn handle_picker(// Legend/controls moved to preview window tabs (render_preview_tabs).build().map_err(|e| anyhow::anyhow!("Failed to build skim options: {}", e))?;+ worktrunk::shell_exec::trace_instant("Picker skim options built");let (tx, rx): (SkimItemSender, SkimItemReceiver) = unbounded();@@ -543,6 +630,7 @@ pub fn handle_picker();}).context("Failed to spawn picker-collect thread")?;+ worktrunk::shell_exec::trace_instant("Picker collect spawned");// Drop main-thread copies so the bg thread's `tx` clone is the last// sender (its drop is what stops skim's heartbeat).