Skip to content

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.rs
index 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 serialization
Ok(Some(super::model::ListData {
diff --git a/src/commands/list/mod.rs b/src/commands/list/mod.rs
index 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.rs
index 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 behavior
diff --git a/src/shell_exec.rs b/src/shell_exec.rs
index 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,