Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Document list command performance and git caching behavior
Maximilian Roos7b1665b5e3e2
diff --git a/src/commands/list/mod.rs b/src/commands/list/mod.rsindex bcc0141ff..6205faaf7 100644--- a/src/commands/list/mod.rs+++ b/src/commands/list/mod.rs@@ -1,3 +1,79 @@+//! List command for displaying worktrees and branches.+//!+//! # Performance+//!+//! `wt list` runs multiple git commands per worktree in parallel using Rayon. Performance+//! depends heavily on git's internal caches, not worktrunk-specific caching.+//!+//! ## Git Commands Per Worktree+//!+//! For each worktree, we execute:+//! - `git status --porcelain` - Working tree state (uses index cache)+//! - `git rev-list --count <base>..<head>` - Ahead/behind counts (uses commit graph)+//! - `git diff --numstat HEAD` - Working tree line diffs (uses index + tree objects)+//! - `git diff --numstat <base>...<head>` - Branch line diffs (uses tree objects)+//! - `git rev-parse <ref>` - Ref resolution (uses ref cache)+//!+//! Plus one global command:+//! - `git worktree list --porcelain` - List all worktrees (uses ref cache)+//!+//! ## Git's Internal Caches+//!+//! Git caches significantly affect performance. These caches are maintained by git itself:+//!+//! 1. **Index (`.git/index`)** - Cached file metadata (mtime, size, mode)+//! - Speeds up `git status` by avoiding full file content comparisons+//! - Invalidated when files change or staging area updates+//! - Cold: ~100ms per worktree, Warm: ~10ms per worktree (typical repo)+//!+//! 2. **Commit graph (`.git/objects/info/commit-graph`)** - Precomputed commit metadata+//! - Speeds up `git rev-list --count` by avoiding commit object parsing+//! - Generated by `git commit-graph write` (some repos auto-generate)+//! - Without: O(commits) parsing, With: O(1) metadata lookup+//! - Cold: ~50ms for 1000 commits, Warm: ~5ms (with commit graph)+//!+//! 3. **Ref cache (`.git/refs/` and `.git/packed-refs`)** - Cached ref resolutions+//! - Speeds up `git rev-parse` and branch lookups+//! - Packed refs improve performance in repos with many branches+//! - Cold: ~10ms, Warm: <1ms+//!+//! 4. **Filesystem cache (OS-level)** - Recently accessed files stay in memory+//! - Speeds up all git operations after first access+//! - Cleared when system is under memory pressure+//! - Most impactful for large repos with many pack files+//!+//! 5. **Pack files (`.git/objects/pack/`)** - Compressed object storage+//! - Faster than loose objects for bulk access+//! - `git gc` consolidates loose objects into packs+//! - More efficient for tree/blob access in diffs+//!+//! ## Worktrunk's Only Cache: Default Branch+//!+//! Worktrunk caches only the default branch name (main/master) using `git remote set-head`.+//! This is a git-native cache stored in `.git/refs/remotes/origin/HEAD`. All other data is+//! fetched fresh on each `wt list` invocation.+//!+//! Refresh with: `wt config refresh-cache`+//!+//! ## Performance Characteristics+//!+//! Scaling (from benches/list.rs):+//! - Linear with worktree count due to parallelization (Rayon thread pool)+//! - Dominated by git command overhead, not Rust code+//! - Cold caches: ~150-300ms per worktree (typical repo, 500 commits, 100 files)+//! - Warm caches: ~20-50ms per worktree+//! - Real-world: rust-lang/rust repo with 8 worktrees: ~400ms (warm caches)+//!+//! Bottlenecks:+//! 1. `git status --porcelain` - Slowest when index is cold or many files changed+//! 2. `git rev-list --count` - Slow without commit graph in repos with deep history+//! 3. `git diff --numstat` - Slow for large diffs or when pack files aren't cached+//!+//! Optimization tips:+//! - Run `git commit-graph write --reachable --changed-paths` to speed up commit counting+//! - Run `git gc` periodically to consolidate objects into pack files+//! - Minimize uncommitted changes across worktrees (each dirty worktree adds diff overhead)+mod ci_status;mod columns;mod layout;