Skip to content

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.rs
index 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;