Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Refactor documentation for clarity and accuracy
Maximilian Roos10e89d0596a6
diff --git a/src/commands/list/collect.rs b/src/commands/list/collect.rsindex 117da87a3..851fd5286 100644--- a/src/commands/list/collect.rs+++ b/src/commands/list/collect.rs@@ -21,10 +21,10 @@//!//! | Command | Purpose |//! |---------|---------|-//! | `git worktree list` | Enumerate worktrees |+//! | `git worktree list --porcelain` | 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 config --bool core.bare` | Bare repo check for expected-path logic |//! | `git for-each-ref refs/heads` | Only with `--branches` flag |//! | `git for-each-ref refs/remotes` | Only with `--remotes` flag |//!@@ -57,7 +57,8 @@//!//! Progressive and buffered modes use the same collection and rendering code.//! The only difference is whether intermediate updates are shown during collection:-//! - Progressive: shows progress bars with updates, then finalizes in place (TTY) or redraws (non-TTY)+//! - Progressive: renders a skeleton table and updates rows/footer as data arrives (TTY),+//! or renders once at the end (non-TTY)//! - Buffered: collects silently, then renders the final table//!//! Both modes render the final table in `collect()`, ensuring a single canonical rendering path.@@ -429,7 +430,7 @@ fn apply_default(items: &mut [ListItem], status_contexts: &mut [StatusContext],/// This is the shared logic between progressive and buffered collection modes./// The `on_result` callback is called after each result is processed with the/// item index and a reference to the updated item, allowing progressive mode-/// to update progress bars while buffered mode does nothing.+/// to update the live table while buffered mode does nothing.////// Uses a 30-second deadline to prevent infinite hangs if git commands stall./// When timeout occurs, returns `DrainOutcome::TimedOut` with diagnostic info.@@ -1291,8 +1292,8 @@ pub fn collect(// Table rendering complete (when render_table=true):// - Progressive + TTY: rows morphed in place, footer became summary- // - Progressive + Non-TTY: cleared progress bars, rendered final table- // - Buffered: rendered final table (no progress bars)+ // - Progressive + Non-TTY: rendered final table (no intermediate output)+ // - Buffered: rendered final table// JSON mode (render_table=false): no rendering, data returned for serializationOk(Some(super::model::ListData {diff --git a/src/commands/list/mod.rs b/src/commands/list/mod.rsindex ac327a13b..2fae4e9f3 100644--- a/src/commands/list/mod.rs+++ b/src/commands/list/mod.rs@@ -14,8 +14,9 @@//! - Uses ref cache, very fast//!//! 2. **Default branch lookup** (~1-5ms)-//! - Reads cached value from `.git/refs/remotes/origin/HEAD`-//! - Falls back to `git remote show origin` if not cached (~100-300ms network)+//! - Reads cached value from `git config worktrunk.default-branch`+//! - Falls back to git's remote HEAD ref (e.g., `origin/HEAD`) if available+//! - If still unknown, queries `git ls-remote --symref <remote> HEAD` (~100ms-2s network)//! - Clear cache with `wt config state default-branch clear` to force re-detection//!//! 3. **Sort worktrees** (<1ms)@@ -91,9 +92,10 @@//!//! ## 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.+//! Worktrunk caches only the default branch name (main/master) in+//! `git config worktrunk.default-branch`. The remote HEAD ref (e.g., `origin/HEAD`)+//! is git's cache; worktrunk reads it but does not set it. All other data is fetched+//! fresh on each `wt list` invocation.//!//! Clear cache with: `wt config state default-branch clear`//!diff --git a/src/help_pager.rs b/src/help_pager.rsindex 97c060f60..5d01ba0d3 100644--- a/src/help_pager.rs+++ b/src/help_pager.rs@@ -17,8 +17,9 @@//!//! # Cross-Platform Support//!-//! On Windows, the pager uses Git Bash (if available) to support standard pager-//! commands like `less`. If Git Bash is not available, falls back to direct output.+//! On Windows, Git Bash (if available) enables standard pagers like `less`.+//! Without Git Bash, we only use a pager if the configured command works under+//! the PowerShell fallback; otherwise we print directly.use std::io::{IsTerminal, Write};use std::process::Stdio;@@ -63,9 +64,9 @@ fn detect_help_pager() -> Option<String> {/// Show help text through a pager with TTY access for interactive scrolling.///-/// Only uses pager when stdout is a terminal. Falls back to direct output if:+/// Only uses pager when stdout or stderr is a terminal. Falls back to direct output if:/// - No pager configured (prints to stderr)-/// - stdout is not a TTY (prints to stderr)+/// - Neither stdout nor stderr is a TTY (prints to stderr)/// - Pager spawn fails (prints to stderr)////// Note: All fallbacks output to stderr for consistency with pager behaviordiff --git a/src/shell_exec.rs b/src/shell_exec.rsindex 2559f3b9c..74e7267a4 100644--- a/src/shell_exec.rs+++ b/src/shell_exec.rs@@ -1,7 +1,7 @@//! Cross-platform shell execution//!//! Provides a unified interface for executing shell commands across platforms:-//! - Unix: Uses `/bin/sh -c`+//! - Unix: Uses `sh -c` (resolved via PATH)//! - Windows: Prefers Git Bash if available, falls back to PowerShell//!//! This enables hooks and commands to use the same bash syntax on all platforms,