Skip to content

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

Refactor documentation for clarity and accuracy

Maximilian Roos9e207fbfd5b9
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 8733b62fe..e5355a7e0 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -58,7 +58,8 @@ pub enum StepCommand {
/// Fast-forward target to current branch
///
/// Updates the local target branch (e.g., `main`) to include current commits.
- /// Equivalent to `git push . HEAD:main`.
+ /// Similar to `git push . HEAD:<target>` but uses
+ /// `receive.denyCurrentBranch=updateInstead` internally.
Push {
/// Target branch
///
diff --git a/src/commands/list/collect.rs b/src/commands/list/collect.rs
index 851fd5286..6a83cf53a 100644
--- a/src/commands/list/collect.rs
+++ b/src/commands/list/collect.rs
@@ -64,8 +64,9 @@
//! Both modes render the final table in `collect()`, ensuring a single canonical rendering path.
//!
//! **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.
+//! work queue and processed via Rayon's thread pool. This avoids nested parallelism and keeps
+//! utilization high regardless of worktree count (pool size is set at startup; default is 2x CPU
+//! cores unless `RAYON_NUM_THREADS` is set).
//!
//! **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
@@ -1015,7 +1016,8 @@ pub fn collect(
// Collect all work items upfront, then execute in a single Rayon pool.
// This avoids nested parallelism (Rayon par_iter → thread::scope per worktree)
- // which could create 100+ threads. Instead, we have one pool with ~8 threads.
+ // which could create 100+ threads. Instead, we have one pool with the configured
+ // thread count (default 2x CPU cores unless overridden by RAYON_NUM_THREADS).
let sorted_worktrees_clone = sorted_worktrees.clone();
let tx_worker = tx.clone();
let expected_results_clone = expected_results.clone();
diff --git a/src/commands/list/collect_progressive_impl.rs b/src/commands/list/collect_progressive_impl.rs
index 62c12dad9..56f706d77 100644
--- a/src/commands/list/collect_progressive_impl.rs
+++ b/src/commands/list/collect_progressive_impl.rs
@@ -11,7 +11,8 @@
//! generate `WorkItem` instances for each task, registering expected results upfront.
//!
//! 2. **Parallel execution**: All work items are collected into a `Vec` and processed
-//! via `into_par_iter()`. Rayon schedules optimally across its thread pool (~8 threads).
+//! via `into_par_iter()`. Rayon schedules across its thread pool (size set at startup,
+//! defaulting to 2x CPU cores unless `RAYON_NUM_THREADS` is set).
//!
//! 3. **Result delivery**: Each `WorkItem::execute()` returns a result; the caller sends it.
//!
diff --git a/src/commands/list/render.rs b/src/commands/list/render.rs
index ed9fef567..f685c20ed 100644
--- a/src/commands/list/render.rs
+++ b/src/commands/list/render.rs
@@ -271,7 +271,8 @@ impl LayoutConfig {
/// Render a skeleton row showing known data (branch, path) with placeholders for other columns.
///
- /// Only called for worktrees (not branches), so we can extract is_current/is_previous from WorktreeData.
+ /// Used for both worktrees and branch-only items; branch-only rows render an empty path
+ /// and a blank gutter placeholder.
pub fn format_skeleton_row(&self, item: &super::model::ListItem) -> String {
use crate::display::shorten_path;
diff --git a/src/main.rs b/src/main.rs
index 937ec1865..26429616d 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -153,7 +153,7 @@ pub fn was_invoked_with_explicit_path() -> bool {
/// Custom help handling for pager support and markdown rendering.
///
/// We intercept help requests to provide:
-/// 1. **Pager support**: Help is shown through `less` (like git)
+/// 1. **Pager support**: Help is shown through the detected pager (git-style precedence)
/// 2. **Markdown rendering**: `## Headers` become green, code blocks are dimmed
///
/// Uses `Error::render()` to get clap's pre-formatted help, which already