Skip to content

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

docs(list): document pre-skeleton fork inventory (#2883)

Maximilian Roos8668b4c3389c
diff --git a/src/commands/list/collect/mod.rs b/src/commands/list/collect/mod.rs
index 7dea67c93..375989257 100644
--- a/src/commands/list/collect/mod.rs
+++ b/src/commands/list/collect/mod.rs
@@ -10,50 +10,104 @@
//! 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.
//!
-//! ### Fixed Command Count (O(1), not O(N))
+//! ### Forks on the Critical Path
//!
-//! 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 log --no-walk` command
-//! - **Parallelization** — independent commands run concurrently via `join!` macro
+//! A steady-state run reaches the skeleton through five `git` subprocess
+//! forks (six in repos with `extensions.worktreeConfig=true` — see #3
+//! below). Fork *count* is O(1) — independent of worktree or branch
+//! count — because each batches as much as it can. Fork *work* scales with
+//! N (refs read, SHAs resolved); on a fast Linux system N=40 lands
+//! ~30–80 ms.
//!
-//! **Steady-state (6-8 commands):**
+//! | # | Command | Source | Role |
+//! |---|---------|--------|------|
+//! | 1 | `git rev-parse --git-common-dir --is-inside-work-tree --show-toplevel --git-dir --symbolic-full-name HEAD` | [`Repository::prewarm`] (`prewarm_rev_parse`) | Five facts in one fork: shared `.git`, in-worktree gate, worktree root, per-worktree `.git/worktrees/<name>`, current branch. Populates process-global caches. Parallel with #2 at process startup. |
+//! | 2 | `git config --list -z` (cwd = discovery path) | [`Repository::prewarm`] (`prewarm_git_config`) | Whole merged config (system + global + local) in one shot, NUL-delimited so values containing `\n` or `=` parse unambiguously. Stashed in `GIT_CONFIG_PRELOAD` keyed by discovery path; every later `config_last("…")` reads from memory. Parallel with #1. |
+//! | 3 | `git config --list -z` (cwd = `git_common_dir`) | [`Repository::all_config`] | **Conditional.** [`Repository::at`] consumes #2's preload into `cache.all_config`, so `all_config()` is a memory hit on a normal repo. This fork only fires when `prewarm_git_config` declined the preload because `extensions.worktreeConfig=true` — there `--list` from a linked worktree misses the main-worktree `config.worktree` overrides (most importantly `core.bare = true` for the `myproject/.git + sibling worktrees` layout), so `all_config` re-forks from the common dir to see the full merged set. See `prewarm_git_config` for the full reasoning. |
+//! | 4 | `git worktree list --porcelain` | [`Repository::list_worktrees`] | Path, HEAD SHA, branch, and flags per worktree — the row source for the skeleton. The picker prelude triggers this once for `num_items_estimate`; collect's rayon scope then hits the cache. |
+//! | 5 | `git for-each-ref --format=… refs/heads/` | [`Repository::local_branches`] inside collect's `rayon::scope` | Local branch tips (name, SHA, committer date, upstream) for branch-only rows (`branches=true`) and for the stale-default-branch check. `remotes=true` adds a sibling `refs/remotes/` fork. The scope joins; this fork gates the skeleton. |
+//! | 6 | `git log --no-walk --no-show-signature --format=… SHA₁ … SHA_N` | collect, after the scope | Batched commit metadata for every worktree HEAD + branch tip. See breakdown below. |
//!
-//! | Command | Purpose | Parallel |
-//! |---------|---------|----------|
-//! | `git worktree list --porcelain` | Enumerate worktrees | ✓ |
-//! | `git config worktrunk.default-branch` | Cached default branch | ✓ |
-//! | `git config --bool core.bare` | Bare repo check for expected-path logic | ✓ |
-//! | `git rev-parse --show-toplevel` | Worktree root for project config | ✓ |
-//! | `git config remote.*.url` (1-3 calls) | Project identifier (for config + path check) | ✓ |
-//! | `git for-each-ref refs/heads` | Only with `--branches` flag | ✓ |
-//! | `git for-each-ref refs/remotes` | Only with `--remotes` flag | ✓ |
-//! | `git log --no-walk --format='%H\0%ct\0%s' SHA1 SHA2 ...` | **Batched** commit details (timestamp + subject) | Sequential (needs SHAs) |
+//! Things that *look* like forks but aren't, on the steady-state path:
+//! `git config worktrunk.default-branch`, `git config --bool core.bare`,
+//! `git config remote.*.url`, [`Repository::is_bare`] — each is a
+//! `config_last("…")` lookup served from #2's in-memory map (or from #3
+//! when the conditional fork above did fire). They appear in the rayon
+//! scope as logical fetches but no subprocess fires for them warm. The
+//! same is true for [`Repository::default_branch`] once
+//! `worktrunk.default-branch` is cached (the steady-state case).
+//!
+//! Things that fire **once per repo, ever**:
+//!
+//! - [`Repository::default_branch`] falling through to
+//! `git ls-remote --symref <remote> HEAD` when neither
+//! `worktrunk.default-branch` nor `refs/remotes/<remote>/HEAD` is set.
+//! 100 ms – 2 s on the wire. The result persists to
+//! `worktrunk.default-branch` so subsequent runs are a cache hit. This is
+//! worktrunk's one accepted wire-path exception — see CLAUDE.md →
+//! "Network Access".
+//!
+//! ### #6 — the batched commit-details fork
+//!
+//! ```text
+//! git log --no-walk --no-show-signature \
+//! --format=%H%x00%h%x00%ct%x00%s \
+//! SHA₁ SHA₂ … SHA_N
+//! ```
+//!
+//! - `--no-walk` — don't traverse history. Without it, `git log SHA₁ SHA₂`
+//! walks the ancestry of each starting point and prints thousands of
+//! commits. With it, one record per named SHA. Turns this from
+//! O(history) into O(N refs).
+//! - `--no-show-signature` — skip GPG verification. If `gpg.program` is set
+//! and any of these commits are signed, the default forks `gpg` per
+//! commit; disabled here.
+//! - `--format=%H%x00%h%x00%ct%x00%s` — four fields per commit,
+//! NUL-separated because subjects can contain anything except NUL:
+//! - `%H` full SHA, `%h` abbreviated SHA, `%ct` committer date (Unix
+//! epoch), `%s` subject (first line of message).
+//!
+//! SHAs come from #4 (worktree HEADs) ∪ #5 (branch tips), deduplicated.
+//! Argv length scales with N — Linux `ARG_MAX` (~128 KB) bounds the
+//! unchunked form at roughly 3,000 SHAs.
+//!
+//! What each field feeds:
+//! - `%ct` — sort order on the skeleton. This is the *only* reason #6 is
+//! pre-skeleton; the skeleton can't pick row order without it.
+//! - `%ct` again, post-skeleton — Age column ("3 hours ago").
+//! - `%s` post-skeleton — Message column.
+//! - `%h` post-skeleton — abbreviated-SHA cell.
+//!
+//! Subjects and abbreviated SHAs ride along for free: git resolves each
+//! commit object to read its timestamp anyway, so the extra bytes add no
+//! measurable latency to the round trip. Without this batch you'd be
+//! forking `git log -1` per SHA later — same data, N forks instead of one.
+//! The full `(timestamp, subject)` map is handed to the post-skeleton loop
+//! that populates `ListItem.commit` directly.
//!
-//! The batched `git log` fetches subjects too, which the skeleton itself
-//! doesn't strictly need — only timestamps are required for sort order. It
-//! rides along for free: git has to resolve each commit object anyway, and
-//! the subject bytes add no measurable latency to the round trip. The
-//! full `(timestamp, subject)` map is handed to the post-skeleton loop that
-//! populates `ListItem.commit` directly — no per-SHA `git log -1` fork path.
//! When the batch fails (e.g., a listed SHA was deleted mid-run), the
//! failure is surfaced once and Age/Message cells render placeholders for
//! that run.
//!
-//! **Non-git operations (negligible latency):**
-//! - Path canonicalization — detect current worktree
-//! - Project config file read — check if URL column needed (no template expansion)
-//! - Config resolution — merge project-specific settings (uses cached project identifier)
+//! ### Non-git work on the path
//!
-//! ### First-Run Behavior
+//! Negligible latency, but worth naming:
+//! - Path canonicalization — detect current worktree.
+//! - Project config file read (`.config/wt.toml`) via
+//! `ProjectConfig::load`. [`Repository::url_template`] reads `list.url`
+//! from this file — TOML I/O, not git config, and no subprocess.
+//! - Config resolution — merge project-specific settings (uses cached
+//! project identifier).
//!
-//! 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`
+//! ### First-run behavior
//!
-//! Subsequent runs use the cached value — only one `git config` call.
+//! On a fresh clone with `worktrunk.default-branch` unset,
+//! [`Repository::default_branch`] adds one extra step on the path: try
+//! `refs/remotes/<remote>/HEAD` locally, fall through to
+//! `git ls-remote --symref` (the wire-path exception above), fall further
+//! back to local inference (`init.defaultBranch`, common branch names).
+//! The result is cached to `worktrunk.default-branch` so every subsequent
+//! run is a memory hit served from #2.
//!
//! ### Post-Skeleton Operations
//!
diff --git a/src/commands/picker/mod.rs b/src/commands/picker/mod.rs
index a1fe50dff..dfd590cec 100644
--- a/src/commands/picker/mod.rs
+++ b/src/commands/picker/mod.rs
@@ -36,7 +36,9 @@
//! `on_skeleton`.
//!
//! Time-to-skeleton = steps 1-6 on the main thread *plus* collect's
-//! pre-skeleton phase on the bg thread.
+//! pre-skeleton phase on the bg thread. See `commands/list/collect/mod.rs`
+//! § "Forks on the Critical Path" for the subprocess inventory (five
+//! forks, plus one more in `extensions.worktreeConfig` repos).
//!
//! ## Phase timings
//!