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.mdindex 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-SkeletonEverything 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, thenupdate 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 calculationdiff --git a/src/commands/list/collect.rs b/src/commands/list/collect.rsindex 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;