Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(perf): require --progressive in wt-perf trace pipeline and trim duplication (#2258)
Maximilian Roosd2d38dd458d9
diff --git a/benches/CLAUDE.md b/benches/CLAUDE.mdindex 3923a031a..dc8616e94 100644--- a/benches/CLAUDE.md+++ b/benches/CLAUDE.md@@ -87,8 +87,10 @@ cargo run -p wt-perf -- invalidate /tmp/wt-perf-typical-8/main### Generating traces```bash-# Generate trace.json for Perfetto/Chrome-RUST_LOG=debug wt list --branches 2>&1 \+# Generate trace.json for Perfetto/Chrome. `--progressive` forces TTY-gated+# events (Skeleton rendered, First result received) to fire even when stdout+# is piped.+RUST_LOG=debug wt list --progressive --branches 2>&1 \| cargo run -p wt-perf -- trace > trace.json# Open in https://ui.perfetto.dev or chrome://tracing@@ -196,7 +198,7 @@ trace_processor trace.json -q /tmp/q.sql```bash# Trace on rust-lang/rust (must run benchmark first to clone)-RUST_LOG=debug cargo run --release -q -- -C target/bench-repos/rust list --branches 2>&1 \+RUST_LOG=debug cargo run --release -q -- -C target/bench-repos/rust list --progressive --branches 2>&1 \| cargo run -p wt-perf -- trace > rust-trace.json```diff --git a/src/trace/chrome.rs b/src/trace/chrome.rsindex 872faab45..ba4423175 100644--- a/src/trace/chrome.rs+++ b/src/trace/chrome.rs@@ -8,12 +8,7 @@//! - **Complete events** (`ph: "X"`): Command executions with duration//! - **Instant events** (`ph: "I"`): Milestones without duration (e.g., "Showed skeleton")//!-//! # Usage-//!-//! ```bash-//! RUST_LOG=debug wt list 2>&1 | cargo run -p wt-perf -- trace > trace.json-//! # Then open trace.json in chrome://tracing or https://ui.perfetto.dev-//! ```+//! See [`crate::trace`] for the capture pipeline and SQL query examples.//!//! # Format Reference//!diff --git a/src/trace/mod.rs b/src/trace/mod.rsindex 4c4dde977..50bf26389 100644--- a/src/trace/mod.rs+++ b/src/trace/mod.rs@@ -12,8 +12,9 @@//! # Usage//!//! ```bash-//! # Generate Chrome Trace Format-//! RUST_LOG=debug wt list 2>&1 | cargo run -p wt-perf -- trace > trace.json+//! # Generate Chrome Trace Format (--progressive forces TTY-gated events+//! # like `Skeleton rendered` to fire even when stdout is piped)+//! RUST_LOG=debug wt list --progressive 2>&1 | cargo run -p wt-perf -- trace > trace.json//!//! # Visualize: open trace.json in chrome://tracing or https://ui.perfetto.dev//!diff --git a/tests/helpers/wt-perf/src/lib.rs b/tests/helpers/wt-perf/src/lib.rsindex 9adedc294..655588443 100644--- a/tests/helpers/wt-perf/src/lib.rs+++ b/tests/helpers/wt-perf/src/lib.rs@@ -19,18 +19,7 @@//! invalidate_caches_auto(&repo_path);//! ```//!-//! # CLI Usage-//!-//! ```bash-//! # Set up a benchmark repo-//! cargo run -p wt-perf -- setup typical-8-//!-//! # Invalidate caches-//! cargo run -p wt-perf -- invalidate /path/to/repo-//!-//! # Parse trace logs-//! RUST_LOG=debug wt list 2>&1 | cargo run -p wt-perf -- trace-//! ```+//! See `wt-perf --help` for CLI usage.use std::path::{Path, PathBuf};use std::sync::OnceLock;diff --git a/tests/helpers/wt-perf/src/main.rs b/tests/helpers/wt-perf/src/main.rsindex dd8b87681..c375e8766 100644--- a/tests/helpers/wt-perf/src/main.rs+++ b/tests/helpers/wt-perf/src/main.rs@@ -1,20 +1,6 @@//! CLI for worktrunk performance testing and tracing.//!-//! # Usage-//!-//! ```bash-//! # Set up a benchmark repo-//! wt-perf setup typical-8 --path /tmp/bench-//!-//! # Invalidate caches for cold run-//! wt-perf invalidate /tmp/bench/main-//!-//! # Parse trace logs (pipe from wt command)-//! RUST_LOG=debug wt list 2>&1 | wt-perf trace > trace.json-//!-//! # Set up picker test environment-//! wt-perf setup picker-test-//! ```+//! Run `wt-perf --help` (and `wt-perf <subcommand> --help`) for usage.use std::io::{IsTerminal, Read, Write};use std::path::PathBuf;@@ -55,7 +41,9 @@ enum Commands {/// Parse trace logs and output Chrome Trace Format JSON#[command(after_long_help = r#"EXAMPLES:# Generate trace from wt command- RUST_LOG=debug wt list 2>&1 | wt-perf trace > trace.json+ # --progressive is required — without it, TTY-gated events (Skeleton+ # rendered, First result received) don't fire when stdout is a pipe.+ RUST_LOG=debug wt list --progressive 2>&1 | wt-perf trace > trace.json# Then either:# - Open trace.json in chrome://tracing or https://ui.perfetto.dev@@ -75,15 +63,10 @@ enum Commands {/// Analyze trace logs for duplicate commands (cache effectiveness)#[command(after_long_help = r#"EXAMPLES:# Check cache effectiveness for wt list- RUST_LOG=debug wt list 2>&1 | wt-perf cache-check+ RUST_LOG=debug wt list --progressive 2>&1 | wt-perf cache-check# From a filewt-perf cache-check trace.log-- # With a benchmark repo- cargo run -p wt-perf -- setup typical-8 --persist- RUST_LOG=debug wt -C /tmp/wt-perf-typical-8 list 2>&1 \- | cargo run -p wt-perf -- cache-check"#)]CacheCheck {/// Path to trace log file (reads from stdin if omitted)@@ -139,7 +122,7 @@ fn main() {eprintln!("Created: {}", parts.join(", "));eprintln!();eprintln!(- " RUST_LOG=debug wt -C {} list 2>&1 | wt-perf trace > trace.json",+ " RUST_LOG=debug wt -C {} list --progressive 2>&1 | wt-perf trace > trace.json",base_path.display());eprintln!(" wt-perf invalidate {}", base_path.display());@@ -199,10 +182,8 @@ fn read_trace_entries(file: Option<&std::path::Path>) -> Vec<worktrunk::trace::T_ => {if std::io::stdin().is_terminal() {eprintln!(- "\-Reading from stdin... (pipe trace data or use Ctrl+D to end)--Hint: RUST_LOG=debug wt list 2>&1 | wt-perf <subcommand>"+ "Reading from stdin... (pipe trace data or use Ctrl+D to end)\n\+ See `wt-perf <subcommand> --help` for the capture pipeline.");}@@ -219,15 +200,9 @@ Hint: RUST_LOG=debug wt list 2>&1 | wt-perf <subcommand>"if entries.is_empty() {eprintln!(- "\-No trace entries found in input.--Trace lines should look like:- [wt-trace] ts=1234567890 tid=3 cmd=\"git status\" dur_us=12300 ok=true- [wt-trace] ts=1234567890 tid=3 event=\"Showed skeleton\"--To capture traces, run with RUST_LOG=debug:- RUST_LOG=debug wt list 2>&1 | wt-perf <subcommand>"+ "No [wt-trace] entries found in input.\n\+ Run the target command with RUST_LOG=debug to emit trace records.\n\+ See `wt-perf <subcommand> --help` for the capture pipeline.");std::process::exit(1);}diff --git a/tests/integration_tests/analyze_trace.rs b/tests/integration_tests/analyze_trace.rsindex 2bbfb30b3..ea242f372 100644--- a/tests/integration_tests/analyze_trace.rs+++ b/tests/integration_tests/analyze_trace.rs@@ -108,7 +108,7 @@ fn test_wt_perf_trace_empty_input() {let stderr = String::from_utf8_lossy(&output.stderr);assert!(- stderr.contains("No trace entries found"),+ stderr.contains("No [wt-trace] entries found"),"Should indicate no trace entries");}