Skip to content

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

Refactor list command documentation and batching

Maximilian Roosd4698b1abec3
diff --git a/src/commands/list/CLAUDE.md b/src/commands/list/CLAUDE.md
index 9fb544285..40ee6203d 100644
--- a/src/commands/list/CLAUDE.md
+++ b/src/commands/list/CLAUDE.md
@@ -11,28 +11,11 @@ skeleton adds perceived latency. Users notice 50ms vs 150ms.
## Rendering Phases
-### Phase 1: Pre-Skeleton (KEEP THIS MINIMAL)
+### Phase 1: Pre-Skeleton
-Operations that MUST complete before showing anything:
-
-1. `git worktree list` — enumerate worktrees
-2. `git config worktrunk.default-branch` — identify main branch for sorting
-3. `git show -s --format='%H %ct'` — batch timestamp fetch for sorting
-4. `git rev-parse --is-bare-repository` — layout decision (show Path column?)
-5. Path canonicalization — detect current worktree (no git command)
-6. Project config check — read `.config/wt.toml` to check if URL column needed
-7. Layout calculation — column widths from branch/path lengths (no git command)
-
-With `--branches`/`--remotes`:
-- `git for-each-ref refs/heads` / `refs/remotes`
-
-**DO NOT add operations here without very good reason.** Template expansion,
-per-item computations, network I/O — all must wait until after skeleton.
-
-**TODO: Phase 0 optimization** — Consider a "Phase 0" that renders just the first
-few columns (Branch, Status) without computing widths for all columns. This would
-show *something* even faster, then expand the table as more column widths are
-computed. Trade-off: table width might shift as columns are added.
+Minimal operations before showing anything. Runs a **fixed number of git commands**
+(O(1), not O(N) per worktree) through batching. See `collect.rs` module docstring
+for the exact command list and first-run behavior.
### Phase 2: Skeleton Render
@@ -45,25 +28,11 @@ The skeleton shows:
### Phase 3: Post-Skeleton
Everything else runs after the skeleton appears:
-
-- Previous branch lookup (`get_switch_previous`)
-- Integration target calculation
-- URL template expansion (parallelized in task spawning)
+- Previous branch lookup, integration target calculation
+- URL template expansion (parallelized)
- All background tasks (status, diffs, CI, URL health checks)
-These operations update cells progressively as they complete.
-
-**URL column example:** The skeleton allocates space for the URL column using a
-fast heuristic (checks for `hash_port` in template, no expansion). When hyperlinks
-are supported, the display is `:PORT` (6 chars) instead of the full URL. Template
-expansion happens in task spawning (Phase 3), parallelized across worktrees.
-Two-phase update:
-
-1. URL appears immediately in normal styling (sent before health check task)
-2. If health check fails (port not listening), URL dims
-
-This ensures URLs appear as fast as possible — users see the URL right away,
-then it dims only if the dev server isn't running.
+Results update cells progressively as they complete.
## Adding New Features
@@ -75,12 +44,10 @@ When adding a new column or feature, ask:
2. **Can template expansion wait?** Yes. Expand templates post-skeleton, then
update the relevant cells.
-3. **Does it require file I/O?** If so, it belongs post-skeleton. Reading config
- files, checking file existence, etc. all add latency.
+3. **Does it require file I/O?** If so, it belongs post-skeleton.
**Default answer: defer to post-skeleton.** Only add pre-skeleton operations
-when the skeleton literally cannot render without the data (e.g., we need branch
-names to show anything useful).
+when the skeleton literally cannot render without the data.
## Benchmarking Skeleton Time
@@ -88,12 +55,11 @@ names to show anything useful).
WORKTRUNK_SKELETON_ONLY=1 hyperfine 'wt list'
```
-This exits immediately after rendering the skeleton, measuring pure skeleton
-latency. Target: <60ms.
+Measures pure skeleton latency. Target: <60ms.
## Code Structure
-- `collect.rs` — orchestrates collection, manages pre/post-skeleton phases
+- `collect.rs` — orchestrates collection, manages pre/post-skeleton phases (see module docstring for phase details)
- `collect_progressive_impl.rs` — background task definitions and execution
- `render.rs` — row formatting, skeleton rows, cell rendering
- `layout.rs` — column width calculation
diff --git a/src/commands/list/collect.rs b/src/commands/list/collect.rs
index 6ae9c4125..341c20926 100644
--- a/src/commands/list/collect.rs
+++ b/src/commands/list/collect.rs
@@ -5,21 +5,46 @@
//! - Network tasks (CI, URL) sorted to run last
//! - Progressive updates via channels (update UI as each task completes)
//!
-//! ## Skeleton Performance (IMPORTANT)
+//! ## Skeleton Performance
//!
//! The skeleton (placeholder table with loading indicators) must render as fast as possible
//! to give users immediate feedback. Every git command before skeleton adds latency.
//!
-//! **Minimal pre-skeleton operations (keep this list small!):**
-//! 1. `git worktree list` — get list of worktrees (essential)
-//! 2. `git config worktrunk.default-branch` — identify main worktree for sorting
-//! 3. Path comparison — detect current worktree (NO git command, just canonicalize paths)
-//! 4. `git branch` / `git branch -r` — only if `--branches` / `--remotes` flags
-//! 5. `git show -s --format='%H %ct'` — batch timestamp fetch for sorting
-//! 6. `git rev-parse --is-bare-repository` — for layout (path column visibility)
-//! 7. Project config check — only reads file to check if URL column needed (no expansion)
+//! ### Fixed Command Count (O(1), not O(N))
//!
-//! **Deferred until after skeleton:**
+//! Pre-skeleton runs a **fixed number of git commands** regardless of worktree count.
+//! This is achieved through:
+//! - **Batching** — timestamp fetch passes all SHAs to one `git show` command
+//! - **Parallelization** — independent commands run concurrently via `join!` macro
+//!
+//! **Steady-state (4-6 commands):**
+//!
+//! | Command | Purpose |
+//! |---------|---------|
+//! | `git worktree list` | Enumerate worktrees |
+//! | `git config worktrunk.default-branch` | Cached default branch |
+//! | `git show -s --format='%H %ct' SHA1 SHA2 ...` | **Batched** timestamps for sorting |
+//! | `git rev-parse --is-bare-repository` | Layout decision (show Path column?) |
+//! | `git for-each-ref refs/heads` | Only with `--branches` flag |
+//! | `git for-each-ref refs/remotes` | Only with `--remotes` flag |
+//!
+//! **Non-git operations (negligible latency):**
+//! - Path canonicalization — detect current worktree
+//! - Project config file read — check if URL column needed (no template expansion)
+//!
+//! ### First-Run Behavior
+//!
+//! When `worktrunk.default-branch` is not cached, `default_branch()` runs additional
+//! commands to detect it:
+//! 1. Query primary remote (origin/HEAD or `git ls-remote`)
+//! 2. Fall back to local inference (check init.defaultBranch, common names)
+//! 3. Cache result to `git config worktrunk.default-branch`
+//!
+//! Subsequent runs use the cached value — only one `git config` call.
+//!
+//! ### Post-Skeleton Operations
+//!
+//! Everything else runs **after** the skeleton appears:
//! - `get_switch_previous()` — previous branch detection (updates gutter symbol)
//! - `effective_integration_target()` — upstream vs local target check
//! - URL template expansion — parallelized in task spawning
@@ -40,6 +65,10 @@
//! **Flat parallelism**: All tasks (for all worktrees and branches) are collected into a single
//! work queue and processed via Rayon's thread pool. This avoids nested parallelism and ensures
//! optimal CPU utilization (~8 threads) regardless of worktree count.
+//!
+//! **Task ordering**: Work items are sorted so local git operations run first, network tasks
+//! (CI status, URL health checks) run last. This ensures the table fills in quickly with local
+//! data while slower network requests complete in the background.
use anyhow::Context;
use color_print::cformat;
use crossbeam_channel as chan;