Skip to content

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

docs: improve command documentation structure (#643)

Maximilian Roosd70860afbb95
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index 1b92daa51..9b54c49f3 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -1,6 +1,6 @@
# wt config
-Manages configuration, shell integration, and runtime settings.
+Manage user & project configs. Includes shell integration, hooks, and saved state.
## Examples
@@ -381,7 +381,9 @@ WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \
## Command reference
-wt config - Manage configuration and shell integration
+wt config - Manage user & project configs
+
+Includes shell integration, hooks, and saved state.
Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.md
index af1cf3df8..84eddea34 100644
--- a/.claude-plugin/skills/worktrunk/reference/hook.md
+++ b/.claude-plugin/skills/worktrunk/reference/hook.md
@@ -1,8 +1,8 @@
# wt hook
-Shell commands that run at key points in the worktree lifecycle.
+Run configured hooks
-Hooks run automatically during `wt switch`, `wt merge`, & `wt remove`. `wt hook <type>` runs them on demand. Both user hooks (from `~/.config/worktrunk/config.toml`) and project hooks (from `.config/wt.toml`) are supported.
+Hooks are shell commands that run at key points in the worktree lifecycle — automatically during `wt switch`, `wt merge`, & `wt remove`, or on demand via `wt hook <type>`. Both user (`~/.config/worktrunk/config.toml`) and project (`.config/wt.toml`) hooks are supported.
## Hook types
diff --git a/.claude-plugin/skills/worktrunk/reference/list.md b/.claude-plugin/skills/worktrunk/reference/list.md
index d9cbef778..af6d0ae29 100644
--- a/.claude-plugin/skills/worktrunk/reference/list.md
+++ b/.claude-plugin/skills/worktrunk/reference/list.md
@@ -1,6 +1,8 @@
# wt list
-Show all worktrees with their status. The table includes uncommitted changes, divergence from the default branch and remote, and optional CI status.
+List worktrees and their status
+
+Shows uncommitted changes, divergence from the default branch and remote, and optional CI status.
The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. With `--full`, CI status fetches from the network — the table displays instantly and CI fills in as results arrive.
diff --git a/.claude-plugin/skills/worktrunk/reference/merge.md b/.claude-plugin/skills/worktrunk/reference/merge.md
index dfdccac5f..735dcebfa 100644
--- a/.claude-plugin/skills/worktrunk/reference/merge.md
+++ b/.claude-plugin/skills/worktrunk/reference/merge.md
@@ -1,8 +1,8 @@
# wt merge
-Squash & rebase, fast-forward target, remove the worktree.
+Merge current branch into target. Squash & rebase, fast-forward target, remove the worktree.
-Merge the current branch into the target branch, defaulting to the main branch. Unlike `git merge`, this merges the current branch into a target (rather than a target into the current branch). Similar to clicking "Merge pull request" on GitHub.
+Unlike `git merge`, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
## Examples
@@ -66,7 +66,7 @@ lint = "cargo clippy"
## Command reference
-wt merge - Merge worktree into target branch
+wt merge - Merge current branch into target
Squash &amp; rebase, fast-forward target, remove the worktree.
diff --git a/.claude-plugin/skills/worktrunk/reference/remove.md b/.claude-plugin/skills/worktrunk/reference/remove.md
index 682b181fb..2cdb81f8e 100644
--- a/.claude-plugin/skills/worktrunk/reference/remove.md
+++ b/.claude-plugin/skills/worktrunk/reference/remove.md
@@ -1,6 +1,6 @@
# wt remove
-Removes worktrees and their branches (if merged), returning to the main worktree. Defaults to removing the current worktree.
+Remove worktree; delete branch if merged. For finished feature branches. Removes the current worktree by default.
## Examples
@@ -70,6 +70,8 @@ Removal runs in the background by default (returns immediately). Logs are writte
wt remove - Remove worktree; delete branch if merged
+For finished feature branches. Removes the current worktree by default.
+
Usage: <b><span class=c>wt remove</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCHES]...</span>
<b><span class=g>Arguments:</span></b>
diff --git a/.claude-plugin/skills/worktrunk/reference/select.md b/.claude-plugin/skills/worktrunk/reference/select.md
index 356099b68..f2dea4e09 100644
--- a/.claude-plugin/skills/worktrunk/reference/select.md
+++ b/.claude-plugin/skills/worktrunk/reference/select.md
@@ -1,8 +1,6 @@
# wt select
-Browse and switch worktrees with live preview.
-
-Interactive worktree picker with live preview. Navigate worktrees with keyboard shortcuts and press Enter to switch.
+Interactive worktree selector. Browse and switch worktrees with live preview.
## Examples
diff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/.claude-plugin/skills/worktrunk/reference/step.md
index 85405096f..5fd0cd942 100644
--- a/.claude-plugin/skills/worktrunk/reference/step.md
+++ b/.claude-plugin/skills/worktrunk/reference/step.md
@@ -1,6 +1,6 @@
# wt step
-Run individual git workflow operations: commits, squashes, rebases, and pushes.
+Run individual operations. The building blocks of wt merge — commit, squash, rebase, push — plus standalone utilities.
## Examples
@@ -32,6 +32,9 @@ wt step push
wt step - Run individual operations
+The building blocks of <b>wt merge</b> — commit, squash, rebase, push — plus standalone
+utilities.
+
Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
<b><span class=g>Commands:</span></b>
diff --git a/.claude-plugin/skills/worktrunk/reference/switch.md b/.claude-plugin/skills/worktrunk/reference/switch.md
index c0b4230eb..fd3129081 100644
--- a/.claude-plugin/skills/worktrunk/reference/switch.md
+++ b/.claude-plugin/skills/worktrunk/reference/switch.md
@@ -1,6 +1,6 @@
# wt switch
-Change directory to a worktree, creating one if needed.
+Switch to a worktree. Creates one if needed.
Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
@@ -61,7 +61,7 @@ To change which branch a worktree is on, use `git switch` inside that worktree.
wt switch - Switch to a worktree
-Change directory to a worktree, creating one if needed.
+Creates one if needed.
Usage: <b><span class=c>wt switch</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;BRANCH&gt;</span> <b><span class=c>[--</span></b> <span class=c>&lt;EXECUTE_ARGS&gt;...</span><b><span class=c>]</span></b>
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 634f9edc8..b748c4942 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -139,6 +139,50 @@ After editing, run the sync test (which auto-updates out-of-sync pages):
cargo test --test integration test_command_pages_and_skill_files_are_in_sync
```
+### Command documentation structure
+
+Each command has three documentation pieces in `src/cli.rs`:
+
+| Piece | Source | Purpose |
+|-------|--------|---------|
+| **Definition** | First `///` line | Short identifier for command lists |
+| **Subdefinition** | Second `///` line (optional) | Adds context when relevant |
+| **after_long_help** | `#[command(after_long_help = "...")]` | Full documentation |
+
+**Where each appears:**
+
+| Context | What's shown |
+|---------|--------------|
+| Command list (`wt --help`) | Definition only |
+| Terminal `-h` | Definition in header |
+| Terminal `--help` | Definition (header) + Subdefinition (under header) + after_long_help (after options) |
+| Web docs | "Definition. Subdefinition." as lead paragraph, then after_long_help |
+
+**Content principles:**
+
+1. **Definition must be short** — It appears in command lists; keep it to a noun phrase or brief imperative.
+
+2. **Subdefinition adds context** — Only include if it provides information the definition doesn't. If the definition is complete, omit the subdefinition.
+
+3. **after_long_help must not repeat** — Start with NEW information that expands on or provides context for the definition. Each piece should add information the previous pieces didn't provide.
+
+4. **after_long_help should mostly stand alone** — The opener should give context or purpose, not just continue with details that only make sense after reading the definition. Avoid non-sequiturs.
+
+**Good patterns for after_long_help openers:**
+
+- Explain the mental model: "Worktrees are addressed by branch name..."
+- Contrast with similar tools: "Unlike `git merge`, this merges current into target..."
+- State the use case: "Use when you're done with a feature branch."
+- Explain what something is: "Shell commands that run at key points..."
+- Describe relationship to other commands: "The building blocks of `wt merge`: commit, squash, rebase, push."
+
+**Patterns to avoid:**
+
+- Repeating the definition with different words
+- Starting with details that assume context ("The table shows..." when there's no prior mention of a table)
+- Leading with configuration defaults before establishing what the command does
+- Non-sequiturs that jump to side-effects without context
+
### Example output expansion (wt list)
The `wt list` examples use **HTML comments + code blocks** that expand to full snapshot output. In `cli.rs`, you write:
diff --git a/docs/content/config.md b/docs/content/config.md
index 746d66312..475215507 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -8,7 +8,7 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt config --help-page` — edit cli.rs to update -->
-Manages configuration, shell integration, and runtime settings.
+Manage user & project configs. Includes shell integration, hooks, and saved state.
## Examples
@@ -390,7 +390,9 @@ WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \
## Command reference
{% terminal() %}
-wt config - Manage configuration and shell integration
+wt config - Manage user &amp; project configs
+
+Includes shell integration, hooks, and saved state.
Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 3ac1e01c5..0ab56a9f3 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -8,9 +8,9 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt hook --help-page` — edit cli.rs to update -->
-Shell commands that run at key points in the worktree lifecycle.
+Run configured hooks
-Hooks run automatically during `wt switch`, `wt merge`, & `wt remove`. `wt hook <type>` runs them on demand. Both user hooks (from `~/.config/worktrunk/config.toml`) and project hooks (from `.config/wt.toml`) are supported.
+Hooks are shell commands that run at key points in the worktree lifecycle — automatically during `wt switch`, `wt merge`, & `wt remove`, or on demand via `wt hook <type>`. Both user (`~/.config/worktrunk/config.toml`) and project (`.config/wt.toml`) hooks are supported.
## Hook types
diff --git a/docs/content/list.md b/docs/content/list.md
index 0d516bb9c..53540bbef 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -8,7 +8,9 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt list --help-page` — edit cli.rs to update -->
-Show all worktrees with their status. The table includes uncommitted changes, divergence from the default branch and remote, and optional CI status.
+List worktrees and their status
+
+Shows uncommitted changes, divergence from the default branch and remote, and optional CI status.
<figure class="demo">
<picture>
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 5809c920f..e7ec7c1a7 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -8,9 +8,9 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit cli.rs to update -->
-Squash & rebase, fast-forward target, remove the worktree.
+Merge current branch into target. Squash & rebase, fast-forward target, remove the worktree.
-Merge the current branch into the target branch, defaulting to the main branch. Unlike `git merge`, this merges the current branch into a target (rather than a target into the current branch). Similar to clicking "Merge pull request" on GitHub.
+Unlike `git merge`, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
<figure class="demo">
<picture>
@@ -88,7 +88,7 @@ lint = "cargo clippy"
## Command reference
{% terminal() %}
-wt merge - Merge worktree into target branch
+wt merge - Merge current branch into target
Squash &amp; rebase, fast-forward target, remove the worktree.
diff --git a/docs/content/remove.md b/docs/content/remove.md
index 2df5e50db..a84766865 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -8,7 +8,7 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt remove --help-page` — edit cli.rs to update -->
-Removes worktrees and their branches (if merged), returning to the main worktree. Defaults to removing the current worktree.
+Remove worktree; delete branch if merged. For finished feature branches. Removes the current worktree by default.
## Examples
@@ -84,6 +84,8 @@ Removal runs in the background by default (returns immediately). Logs are writte
{% terminal() %}
wt remove - Remove worktree; delete branch if merged
+For finished feature branches. Removes the current worktree by default.
+
Usage: <b><span class=c>wt remove</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCHES]...</span>
<b><span class=g>Arguments:</span></b>
diff --git a/docs/content/select.md b/docs/content/select.md
index 94c73511a..b7448f64b 100644
--- a/docs/content/select.md
+++ b/docs/content/select.md
@@ -8,9 +8,7 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt select --help-page` — edit cli.rs to update -->
-Browse and switch worktrees with live preview.
-
-Interactive worktree picker with live preview. Navigate worktrees with keyboard shortcuts and press Enter to switch.
+Interactive worktree selector. Browse and switch worktrees with live preview.
<figure class="demo">
<picture>
diff --git a/docs/content/step.md b/docs/content/step.md
index 168e42025..477342d9f 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -8,7 +8,7 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt step --help-page` — edit cli.rs to update -->
-Run individual git workflow operations: commits, squashes, rebases, and pushes.
+Run individual operations. The building blocks of wt merge — commit, squash, rebase, push — plus standalone utilities.
## Examples
@@ -46,6 +46,9 @@ wt step push
{% terminal() %}
wt step - Run individual operations
+The building blocks of <b>wt merge</b> — commit, squash, rebase, push — plus standalone
+utilities.
+
Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
<b><span class=g>Commands:</span></b>
diff --git a/docs/content/switch.md b/docs/content/switch.md
index ed6e7c3cf..743acd411 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -8,7 +8,7 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit cli.rs to update -->
-Change directory to a worktree, creating one if needed.
+Switch to a worktree. Creates one if needed.
Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
@@ -18,7 +18,6 @@ Worktrees are addressed by branch name; paths are computed from a configurable t
<img src="/assets/docs/light/wt-switch.gif" alt="wt switch demo" width="1600" height="900">
</picture>
</figure>
-
## Examples
```bash
@@ -84,7 +83,7 @@ To change which branch a worktree is on, use `git switch` inside that worktree.
{% terminal() %}
wt switch - Switch to a worktree
-Change directory to a worktree, creating one if needed.
+Creates one if needed.
Usage: <b><span class=c>wt switch</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;BRANCH&gt;</span> <b><span class=c>[--</span></b> <span class=c>&lt;EXECUTE_ARGS&gt;...</span><b><span class=c>]</span></b>
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index e0ffd63a8..dd8c04b5d 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -244,11 +244,11 @@ pub(crate) struct Cli {
pub(crate) enum Commands {
/// Switch to a worktree
///
- /// Change directory to a worktree, creating one if needed.
+ /// Creates one if needed.
#[command(
after_long_help = r#"Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
-<!-- demo: wt-switch.gif 1600x900 -->
+<!-- demo: wt-switch.gif 1600x900 -->
## Examples
```console
@@ -377,7 +377,8 @@ To change which branch a worktree is on, use `git switch` inside that worktree.
/// List worktrees and their status
#[command(
- after_long_help = r#"Show all worktrees with their status. The table includes uncommitted changes, divergence from the default branch and remote, and optional CI status.
+ after_long_help = r#"Shows uncommitted changes, divergence from the default branch and remote, and optional CI status.
+
<!-- demo: wt-list.gif 1600x900 -->
The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. With `--full`, CI status fetches from the network — the table displays instantly and CI fills in as results arrive.
@@ -646,10 +647,9 @@ Missing a field that would be generally useful? Open an issue at https://github.
},
/// Remove worktree; delete branch if merged
- #[command(
- after_long_help = r#"Removes worktrees and their branches (if merged), returning to the main worktree. Defaults to removing the current worktree.
-
-## Examples
+ ///
+ /// For finished feature branches. Removes the current worktree by default.
+ #[command(after_long_help = r#"## Examples
Remove current worktree:
@@ -717,8 +717,7 @@ Removal runs in the background by default (returns immediately). Logs are writte
- [`wt merge`](@/merge.md) — Remove worktree after merging
- [`wt list`](@/list.md) — View all worktrees
-"#
- )]
+"#)]
Remove {
/// Branch name [default: current]
#[arg(add = crate::completion::local_branches_completer())]
@@ -756,11 +755,12 @@ Removal runs in the background by default (returns immediately). Logs are writte
force: bool,
},
- /// Merge worktree into target branch
+ /// Merge current branch into target
///
/// Squash & rebase, fast-forward target, remove the worktree.
#[command(
- after_long_help = r#"Merge the current branch into the target branch, defaulting to the main branch. Unlike `git merge`, this merges the current branch into a target (rather than a target into the current branch). Similar to clicking "Merge pull request" on GitHub.
+ after_long_help = r#"Unlike `git merge`, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
+
<!-- demo: wt-merge.gif 1600x900 -->
## Examples
@@ -889,9 +889,7 @@ lint = "cargo clippy"
///
/// Browse and switch worktrees with live preview.
#[cfg_attr(not(unix), command(hide = true))]
- #[command(
- after_long_help = r#"Interactive worktree picker with live preview. Navigate worktrees with keyboard shortcuts and press Enter to switch.
-<!-- demo: wt-select.gif 1600x800 -->
+ #[command(after_long_help = r#"<!-- demo: wt-select.gif 1600x800 -->
## Examples
@@ -941,8 +939,7 @@ This is useful when the default pager doesn't render correctly in the embedded p
- [`wt list`](@/list.md) — Static table view with all worktree metadata
- [`wt switch`](@/switch.md) — Direct switching to a known target branch
-"#
- )]
+"#)]
Select {
/// Include branches without worktrees
#[arg(long)]
@@ -954,11 +951,11 @@ This is useful when the default pager doesn't render correctly in the embedded p
},
/// Run individual operations
+ ///
+ /// The building blocks of `wt merge` — commit, squash, rebase, push — plus standalone utilities.
#[command(
name = "step",
- after_long_help = r#"Run individual git workflow operations: commits, squashes, rebases, and pushes.
-
-## Examples
+ after_long_help = r#"## Examples
Commit with LLM-generated message:
@@ -1001,9 +998,7 @@ wt step push
/// Run configured hooks
#[command(
name = "hook",
- after_long_help = r#"Shell commands that run at key points in the worktree lifecycle.
-
-Hooks run automatically during `wt switch`, `wt merge`, & `wt remove`. `wt hook <type>` runs them on demand. Both user hooks (from `~/.config/worktrunk/config.toml`) and project hooks (from `.config/wt.toml`) are supported.
+ after_long_help = r#"Hooks are shell commands that run at key points in the worktree lifecycle — automatically during `wt switch`, `wt merge`, & `wt remove`, or on demand via `wt hook <type>`. Both user (`~/.config/worktrunk/config.toml`) and project (`.config/wt.toml`) hooks are supported.
## Hook types
@@ -1398,11 +1393,11 @@ For copying dependencies and caches between worktrees, see [`wt step copy-ignore
action: HookCommand,
},
- /// Manage configuration and shell integration
+ /// Manage user & project configs
+ ///
+ /// Includes shell integration, hooks, and saved state.
#[command(
- after_long_help = concat!(r#"Manages configuration, shell integration, and runtime settings.
-
-## Examples
+ after_long_help = concat!(r#"## Examples
Install shell integration (required for directory switching):
diff --git a/src/help.rs b/src/help.rs
index a60cc4849..50d160377 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -274,10 +274,13 @@ fn handle_help_page(args: &[String]) {
_ => None,
};
- // Combine: subtitle followed by after_long_help (conceptual docs)
- let raw_help = match subtitle {
- Some(sub) => format!("{sub}\n\n{after_long_help}"),
- None => after_long_help,
+ // Combine: definition + subtitle as single lead paragraph, then after_long_help
+ // Definition doesn't have trailing period, subtitle does, so join with ". "
+ let raw_help = match (&about, &subtitle) {
+ (Some(def), Some(sub)) => format!("{def}. {sub}\n\n{after_long_help}"),
+ (Some(def), None) => format!("{def}\n\n{after_long_help}"),
+ (None, Some(sub)) => format!("{sub}\n\n{after_long_help}"),
+ (None, None) => after_long_help,
};
// Split content at first subdoc placeholder
@@ -537,9 +540,9 @@ fn expand_demo_placeholders(text: &str) -> String {
// Use figure.demo class for proper mobile styling (no shrink, horizontal scroll)
// Generate <picture> element for light/dark theme switching
// Assets are organized as: /assets/docs/{light,dark}/filename.gif
- // Add blank line before the figure; blank line after is already in source
+ // Blank line after is already in source; blank line before comes from section separation
let replacement = format!(
- "\n<figure class=\"demo\">\n<picture>\n <source srcset=\"/assets/docs/dark/{filename}\" media=\"(prefers-color-scheme: dark)\">\n <img src=\"/assets/docs/light/{filename}\" alt=\"{alt_text} demo\"{dim_attrs}>\n</picture>\n</figure>"
+ "<figure class=\"demo\">\n<picture>\n <source srcset=\"/assets/docs/dark/{filename}\" media=\"(prefers-color-scheme: dark)\">\n <img src=\"/assets/docs/light/{filename}\" alt=\"{alt_text} demo\"{dim_attrs}>\n</picture>\n</figure>"
);
let end = after_prefix + end_offset + SUFFIX.len();
result.replace_range(start..end, &replacement);
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 3c68e4e38..6af84490c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -20,7 +20,9 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt config - Manage configuration and shell integration
+wt config - Manage user & project configs
+
+Includes shell integration, hooks, and saved state.
Usage: wt config [OPTIONS] <COMMAND>
@@ -44,8 +46,6 @@ Usage: wt config [OPTIONS] <COMMAND>
-v, --verbose...
Show debug info (-v), or also write diagnostic report (-vv)
-Manages configuration, shell integration, and runtime settings.
-
Examples
Install shell integration (required for directory switching):
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_short.snap b/tests/snapshots/integration__integration_tests__help__help_config_short.snap
index 8a33e14df..e52660234 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_short.snap
@@ -7,7 +7,7 @@ info:
- "-h"
env:
CLICOLOR_FORCE: "1"
- COLUMNS: "150"
+ COLUMNS: "500"
GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
@@ -20,7 +20,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt config - Manage configuration and shell integration
+wt config - Manage user & project configs
Usage: wt config [OPTIONS] <COMMAND>
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index 51cab067c..056d25395 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -61,7 +61,8 @@ Usage: wt list [OPTIONS]
-v, --verbose...
Show debug info (-v), or also write diagnostic report (-vv)
-Show all worktrees with their status. The table includes uncommitted changes, divergence from the default branch and remote, and optional CI status.
+Shows uncommitted changes, divergence from the default branch and remote, and optional CI status.
+
The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. With --full, CI status fetches from the network — the table displays instantly and CI fills in as results arrive.
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index 6c0a4a8d5..8bb729338 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
@@ -62,8 +62,9 @@ Usage: wt list [OPTIONS]
-v, --verbose...
Show debug info (-v), or also write diagnostic report (-vv)
-Show all worktrees with their status. The table includes uncommitted changes,
-divergence from the default branch and remote, and optional CI status.
+Shows uncommitted changes, divergence from the default branch and remote, and
+optional CI status.
+
The table renders progressively: branch names, paths, and commit hashes appear
immediately, then status, divergence, and other columns fill in as background
diff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
index a1fdc73f7..42e7644f0 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
@@ -18,7 +18,7 @@ info:
success: true
exit_code: 0
----- stdout -----
-wt merge - Merge worktree into target branch
+wt merge - Merge current branch into target
Squash & rebase, fast-forward target, remove the worktree.
@@ -70,7 +70,8 @@ Global Options:
-v, --verbose...
Show debug info (-v), or also write diagnostic report (-vv)
-Merge the current branch into the target branch, defaulting to the main branch. Unlike `git merge`, this merges the current branch into a target (rather than a target into the current branch). Similar to clicking "Merge pull request" on GitHub.
+Unlike `git merge`, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
+
<!-- demo: wt-merge.gif 1600x900 -->
## Examples
diff --git a/tests/snapshots/integration__integration_tests__help__help_md_root.snap b/tests/snapshots/integration__integration_tests__help__help_md_root.snap
index 26ed102b3..46196bdc1 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_root.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_root.snap
@@ -6,7 +6,7 @@ info:
- "--help-md"
env:
CLICOLOR_FORCE: "1"
- COLUMNS: "150"
+ COLUMNS: "500"
GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
@@ -25,11 +25,11 @@ Commands:
switch Switch to a worktree
list List worktrees and their status
remove Remove worktree; delete branch if merged
- merge Merge worktree into target branch
+ merge Merge current branch into target
select Interactive worktree selector
step Run individual operations
hook Run configured hooks
- config Manage configuration and shell integration
+ config Manage user & project configs
Options:
-h, --help
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
index c1e12dbe4..fee7606cc 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -20,7 +20,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt merge - Merge worktree into target branch
+wt merge - Merge current branch into target
Squash & rebase, fast-forward target, remove the worktree.
@@ -72,7 +72,8 @@ Usage: wt merge [OPTIONS] [TARGET]
-v, --verbose...
Show debug info (-v), or also write diagnostic report (-vv)
-Merge the current branch into the target branch, defaulting to the main branch. Unlike git merge, this merges the current branch into a target (rather than a target into the current branch). Similar to clicking "Merge pull request" on GitHub.
+Unlike git merge, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
+
Examples
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_short.snap b/tests/snapshots/integration__integration_tests__help__help_merge_short.snap
index 35a30145a..4f6213ed1 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_short.snap
@@ -7,7 +7,7 @@ info:
- "-h"
env:
CLICOLOR_FORCE: "1"
- COLUMNS: "150"
+ COLUMNS: "500"
GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
@@ -20,7 +20,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt merge - Merge worktree into target branch
+wt merge - Merge current branch into target
Usage: wt merge [OPTIONS] [TARGET]
diff --git a/tests/snapshots/integration__integration_tests__help__help_no_args.snap b/tests/snapshots/integration__integration_tests__help__help_no_args.snap
index 32addd5f5..592d78576 100644
--- a/tests/snapshots/integration__integration_tests__help__help_no_args.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_no_args.snap
@@ -5,7 +5,7 @@ info:
args: []
env:
CLICOLOR_FORCE: "1"
- COLUMNS: "150"
+ COLUMNS: "500"
GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
@@ -26,11 +26,11 @@ Usage: wt [OPTIONS] [COMMAND]
switch Switch to a worktree
list List worktrees and their status
remove Remove worktree; delete branch if merged
- merge Merge worktree into target branch
+ merge Merge current branch into target
select Interactive worktree selector
step Run individual operations
hook Run configured hooks
- config Manage configuration and shell integration
+ config Manage user & project configs
Options:
-h, --help Print help (see more with '--help')
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index bb3776d27..54fbdd621 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -22,6 +22,8 @@ exit_code: 0
----- stderr -----
wt remove - Remove worktree; delete branch if merged
+For finished feature branches. Removes the current worktree by default.
+
Usage: wt remove [OPTIONS] [BRANCHES]...
Arguments:
@@ -62,8 +64,6 @@ Usage: wt remove [OPTIONS] [BRANCHES]...
-v, --verbose...
Show debug info (-v), or also write diagnostic report (-vv)
-Removes worktrees and their branches (if merged), returning to the main worktree. Defaults to removing the current worktree.
-
Examples
Remove current worktree:
diff --git a/tests/snapshots/integration__integration_tests__help__help_root_long.snap b/tests/snapshots/integration__integration_tests__help__help_root_long.snap
index 1267d61f4..cf894889f 100644
--- a/tests/snapshots/integration__integration_tests__help__help_root_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_root_long.snap
@@ -6,7 +6,7 @@ info:
- "--help"
env:
CLICOLOR_FORCE: "1"
- COLUMNS: "150"
+ COLUMNS: "500"
GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
@@ -27,11 +27,11 @@ Usage: wt [OPTIONS] [COMMAND]
switch Switch to a worktree
list List worktrees and their status
remove Remove worktree; delete branch if merged
- merge Merge worktree into target branch
+ merge Merge current branch into target
select Interactive worktree selector
step Run individual operations
hook Run configured hooks
- config Manage configuration and shell integration
+ config Manage user & project configs
Options:
-h, --help
diff --git a/tests/snapshots/integration__integration_tests__help__help_root_short.snap b/tests/snapshots/integration__integration_tests__help__help_root_short.snap
index 7dda419df..86ba8de68 100644
--- a/tests/snapshots/integration__integration_tests__help__help_root_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_root_short.snap
@@ -6,7 +6,7 @@ info:
- "-h"
env:
CLICOLOR_FORCE: "1"
- COLUMNS: "150"
+ COLUMNS: "500"
GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
@@ -27,11 +27,11 @@ Usage: wt [OPTIONS] [COMMAND]
switch Switch to a worktree
list List worktrees and their status
remove Remove worktree; delete branch if merged
- merge Merge worktree into target branch
+ merge Merge current branch into target
select Interactive worktree selector
step Run individual operations
hook Run configured hooks
- config Manage configuration and shell integration
+ config Manage user & project configs
Options:
-h, --help Print help (see more with '--help')
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index 7ccbedf23..151625690 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -22,6 +22,8 @@ exit_code: 0
----- stderr -----
wt step - Run individual operations
+The building blocks of wt merge — commit, squash, rebase, push — plus standalone utilities.
+
Usage: wt step [OPTIONS] <COMMAND>
Commands:
@@ -46,8 +48,6 @@ Usage: wt step [OPTIONS] <COMMAND>
-v, --verbose...
Show debug info (-v), or also write diagnostic report (-vv)
-Run individual git workflow operations: commits, squashes, rebases, and pushes.
-
Examples
Commit with LLM-generated message:
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 20dc161c4..a8a96844e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -22,7 +22,7 @@ exit_code: 0
----- stderr -----
wt switch - Switch to a worktree
-Change directory to a worktree, creating one if needed.
+Creates one if needed.
Usage: wt switch [OPTIONS] <BRANCH> [-- <EXECUTE_ARGS>...]