Skip to content

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

docs: improve subcommand definitions and subdefinitions (#798)

Maximilian Roosc45ff300407c
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index e96168eb9..a943be820 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -513,7 +513,7 @@ wt config state - Manage internal data and cache
Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
<b><span class=g>Commands:</span></b>
- <b><span class=c>default-branch</span></b> Default branch setting
+ <b><span class=c>default-branch</span></b> Default branch detection and override
<b><span class=c>previous-branch</span></b> Previous branch (for <b>wt switch -</b>)
<b><span class=c>ci-status</span></b> CI status cache
<b><span class=c>marker</span></b> Branch markers
@@ -538,7 +538,7 @@ Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span
## wt config state default-branch
-Default branch setting.
+Default branch detection and override.
Useful in scripts to avoid hardcoding `main` or `master`:
@@ -567,7 +567,7 @@ The local inference fallback uses these heuristics in order:
### Command reference
-wt config state default-branch - Default branch setting
+wt config state default-branch - Default branch detection and override
Usage: <b><span class=c>wt config state default-branch</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>
diff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/.claude-plugin/skills/worktrunk/reference/step.md
index 7b48eeb71..713c88e09 100644
--- a/.claude-plugin/skills/worktrunk/reference/step.md
+++ b/.claude-plugin/skills/worktrunk/reference/step.md
@@ -38,7 +38,7 @@ 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>
- <b><span class=c>commit</span></b> Commit changes with LLM commit message
+ <b><span class=c>commit</span></b> Stage and commit with LLM-generated message
<b><span class=c>squash</span></b> Squash commits since branching
<b><span class=c>push</span></b> Fast-forward target to current branch
<b><span class=c>rebase</span></b> Rebase onto target
@@ -61,7 +61,7 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
## wt step commit
-Commit changes with LLM commit message. Stages working tree changes and commits with an LLM-generated message.
+Stage and commit with LLM-generated message.
Stages all changes (including untracked files) and commits with an [LLM-generated message](https://worktrunk.dev/llm-commits/).
@@ -102,9 +102,7 @@ wt step commit --show-prompt | llm -m gpt-5-nano
### Command reference
-wt step commit - Commit changes with LLM commit message
-
-Stages working tree changes and commits with an LLM-generated message.
+wt step commit - Stage and commit with LLM-generated message
Usage: <b><span class=c>wt step commit</span></b> <span class=c>[OPTIONS]</span>
@@ -144,7 +142,7 @@ Usage: <b><span class=c>wt step commit</span></b> <span class=c>[OPTIONS]</span>
## wt step squash
-Squash commits since branching. Stages working tree changes, squashes all commits since diverging from target into one, generates message with LLM.
+Squash commits since branching. Stages changes and generates message with LLM.
Stages all changes (including untracked files), then squashes all commits since diverging from the target branch into a single commit with an [LLM-generated message](https://worktrunk.dev/llm-commits/).
@@ -183,8 +181,7 @@ wt step squash --show-prompt | less
wt step squash - Squash commits since branching
-Stages working tree changes, squashes all commits since diverging from target
-into one, generates message with LLM.
+Stages changes and generates message with LLM.
Usage: <b><span class=c>wt step squash</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>
@@ -230,7 +227,7 @@ Usage: <b><span class=c>wt step squash</span></b> <span class=c>[OPTIONS]</span>
## wt step copy-ignored
-Copy gitignored files to another worktree. By default copies all gitignored files; use .worktreeinclude to limit what gets copied. Useful in hooks to copy build caches and dependencies to new worktrees. Skips symlinks and existing files.
+Copy gitignored files to another worktree. Eliminates cold starts by copying build caches and dependencies.
Git worktrees share the repository but not untracked files. This command copies gitignored files to another worktree, eliminating cold starts.
@@ -317,9 +314,7 @@ The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://c
wt step copy-ignored - Copy gitignored files to another worktree
-By default copies all gitignored files; use <b>.worktreeinclude</b> to limit what gets
-copied. Useful in hooks to copy build caches and dependencies to new worktrees.
-Skips symlinks and existing files.
+Eliminates cold starts by copying build caches and dependencies.
Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]</span>
@@ -352,7 +347,7 @@ Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]<
## wt step for-each
-[experimental] Run command in each worktree.
+[experimental] Run command in each worktree. Executes sequentially with real-time output; continues on failure.
Executes a command sequentially in every worktree with real-time output. Continues on failure and shows a summary at the end.
@@ -394,6 +389,8 @@ Note: This command is experimental and may change in future versions.
wt step for-each - [experimental] Run command in each worktree
+Executes sequentially with real-time output; continues on failure.
+
Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</span> <b><span class=c>--</span></b> <span class=c>&lt;ARGS&gt;...</span>
<b><span class=g>Arguments:</span></b>
diff --git a/docs/content/config.md b/docs/content/config.md
index 9b04e3cb4..c64395d75 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -526,7 +526,7 @@ wt config state - Manage internal data and cache
Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
<b><span class=g>Commands:</span></b>
- <b><span class=c>default-branch</span></b> Default branch setting
+ <b><span class=c>default-branch</span></b> Default branch detection and override
<b><span class=c>previous-branch</span></b> Previous branch (for <b>wt switch -</b>)
<b><span class=c>ci-status</span></b> CI status cache
<b><span class=c>marker</span></b> Branch markers
@@ -552,7 +552,7 @@ Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span
## wt config state default-branch
-Default branch setting.
+Default branch detection and override.
Useful in scripts to avoid hardcoding `main` or `master`:
@@ -582,7 +582,7 @@ The local inference fallback uses these heuristics in order:
### Command reference
{% terminal() %}
-wt config state default-branch - Default branch setting
+wt config state default-branch - Default branch detection and override
Usage: <b><span class=c>wt config state default-branch</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>
diff --git a/docs/content/step.md b/docs/content/step.md
index d13c9706b..c413d2505 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -52,7 +52,7 @@ 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>
- <b><span class=c>commit</span></b> Commit changes with LLM commit message
+ <b><span class=c>commit</span></b> Stage and commit with LLM-generated message
<b><span class=c>squash</span></b> Squash commits since branching
<b><span class=c>push</span></b> Fast-forward target to current branch
<b><span class=c>rebase</span></b> Rebase onto target
@@ -76,7 +76,7 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
## wt step commit
-Commit changes with LLM commit message. Stages working tree changes and commits with an LLM-generated message.
+Stage and commit with LLM-generated message.
Stages all changes (including untracked files) and commits with an [LLM-generated message](@/llm-commits.md).
@@ -118,9 +118,7 @@ wt step commit --show-prompt | llm -m gpt-5-nano
### Command reference
{% terminal() %}
-wt step commit - Commit changes with LLM commit message
-
-Stages working tree changes and commits with an LLM-generated message.
+wt step commit - Stage and commit with LLM-generated message
Usage: <b><span class=c>wt step commit</span></b> <span class=c>[OPTIONS]</span>
@@ -161,7 +159,7 @@ Usage: <b><span class=c>wt step commit</span></b> <span class=c>[OPTIONS]</span>
## wt step squash
-Squash commits since branching. Stages working tree changes, squashes all commits since diverging from target into one, generates message with LLM.
+Squash commits since branching. Stages changes and generates message with LLM.
Stages all changes (including untracked files), then squashes all commits since diverging from the target branch into a single commit with an [LLM-generated message](@/llm-commits.md).
@@ -201,8 +199,7 @@ wt step squash --show-prompt | less
{% terminal() %}
wt step squash - Squash commits since branching
-Stages working tree changes, squashes all commits since diverging from target
-into one, generates message with LLM.
+Stages changes and generates message with LLM.
Usage: <b><span class=c>wt step squash</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>
@@ -249,7 +246,7 @@ Usage: <b><span class=c>wt step squash</span></b> <span class=c>[OPTIONS]</span>
## wt step copy-ignored
-Copy gitignored files to another worktree. By default copies all gitignored files; use .worktreeinclude to limit what gets copied. Useful in hooks to copy build caches and dependencies to new worktrees. Skips symlinks and existing files.
+Copy gitignored files to another worktree. Eliminates cold starts by copying build caches and dependencies.
Git worktrees share the repository but not untracked files. This command copies gitignored files to another worktree, eliminating cold starts.
@@ -337,9 +334,7 @@ The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://c
{% terminal() %}
wt step copy-ignored - Copy gitignored files to another worktree
-By default copies all gitignored files; use <b>.worktreeinclude</b> to limit what gets
-copied. Useful in hooks to copy build caches and dependencies to new worktrees.
-Skips symlinks and existing files.
+Eliminates cold starts by copying build caches and dependencies.
Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]</span>
@@ -373,7 +368,7 @@ Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]<
## wt step for-each
-[experimental] Run command in each worktree.
+[experimental] Run command in each worktree. Executes sequentially with real-time output; continues on failure.
Executes a command sequentially in every worktree with real-time output. Continues on failure and shows a summary at the end.
@@ -416,6 +411,8 @@ Note: This command is experimental and may change in future versions.
{% terminal() %}
wt step for-each - [experimental] Run command in each worktree
+Executes sequentially with real-time output; continues on failure.
+
Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</span> <b><span class=c>--</span></b> <span class=c>&lt;ARGS&gt;...</span>
<b><span class=g>Arguments:</span></b>
diff --git a/src/cli/config.rs b/src/cli/config.rs
index f6b7ac80f..c8a5f6edc 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -287,7 +287,7 @@ wt config state clear
#[derive(Subcommand)]
pub enum StateCommand {
- /// Default branch setting
+ /// Default branch detection and override
#[command(
name = "default-branch",
after_long_help = r#"Useful in scripts to avoid hardcoding `main` or `master`:
diff --git a/src/cli/list.rs b/src/cli/list.rs
index b48c2d08b..3425245a7 100644
--- a/src/cli/list.rs
+++ b/src/cli/list.rs
@@ -4,9 +4,7 @@ use clap::Subcommand;
#[derive(Subcommand)]
pub enum ListSubcommand {
/// Single-line status for shell prompts
- ///
- /// For shell prompts, starship, or editor integrations.
- #[command(after_long_help = "Format: `branch status ±working commits upstream ci`")]
+ #[command(after_long_help = "Output format: `branch status ±working commits upstream ci`")]
Statusline {
/// Claude Code mode: read context from stdin, add directory and model
///
diff --git a/src/cli/step.rs b/src/cli/step.rs
index d8d4e8b89..7222d7c03 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -3,9 +3,7 @@ use clap::Subcommand;
/// Run individual operations
#[derive(Subcommand)]
pub enum StepCommand {
- /// Commit changes with LLM commit message
- ///
- /// Stages working tree changes and commits with an LLM-generated message.
+ /// Stage and commit with LLM-generated message
#[command(
after_long_help = r#"Stages all changes (including untracked files) and commits with an [LLM-generated message](@/llm-commits.md).
@@ -67,7 +65,7 @@ wt step commit --show-prompt | llm -m gpt-5-nano
/// Squash commits since branching
///
- /// Stages working tree changes, squashes all commits since diverging from target into one, generates message with LLM.
+ /// Stages changes and generates message with LLM.
#[command(
after_long_help = r#"Stages all changes (including untracked files), then squashes all commits since diverging from the target branch into a single commit with an [LLM-generated message](@/llm-commits.md).
@@ -130,10 +128,19 @@ wt step squash --show-prompt | less
},
/// Fast-forward target to current branch
- ///
- /// Updates the local target branch (e.g., `main`) to include current commits.
- /// Similar to `git push . HEAD:<target>`, but uses
- /// `receive.denyCurrentBranch=updateInstead` internally.
+ #[command(
+ after_long_help = r#"Updates the local target branch (e.g., `main`) to include current commits.
+
+## Examples
+
+```console
+wt step push # Fast-forward main to current branch
+wt step push develop # Fast-forward develop instead
+```
+
+Similar to `git push . HEAD:<target>`, but uses `receive.denyCurrentBranch=updateInstead` internally.
+"#
+ )]
Push {
/// Target branch
///
@@ -143,6 +150,17 @@ wt step squash --show-prompt | less
},
/// Rebase onto target
+ #[command(
+ after_long_help = r#"Rebases the current branch onto the target branch. Conflicts abort immediately; use `git rebase --abort` to recover.
+
+## Examples
+
+```console
+wt step rebase # Rebase onto default branch
+wt step rebase develop # Rebase onto develop
+```
+"#
+ )]
Rebase {
/// Target branch
///
@@ -153,9 +171,7 @@ wt step squash --show-prompt | less
/// Copy gitignored files to another worktree
///
- /// By default copies all gitignored files; use `.worktreeinclude` to limit
- /// what gets copied. Useful in hooks to copy build caches and dependencies
- /// to new worktrees. Skips symlinks and existing files.
+ /// Eliminates cold starts by copying build caches and dependencies.
#[command(
after_long_help = r#"Git worktrees share the repository but not untracked files. This command copies gitignored files to another worktree, eliminating cold starts.
@@ -258,6 +274,8 @@ The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://c
},
/// \[experimental\] Run command in each worktree
+ ///
+ /// Executes sequentially with real-time output; continues on failure.
#[command(
after_long_help = r#"Executes a command sequentially in every worktree with real-time output. Continues on failure and shows a summary at the end.
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state.snap b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
index 281ec539b..a7c61a82d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
@@ -28,7 +28,7 @@ wt config state - Manage internal data and cache
Usage: wt config state [OPTIONS] <COMMAND>
Commands:
- default-branch Default branch setting
+ default-branch Default branch detection and override
previous-branch Previous branch (for wt switch -)
ci-status CI status cache
marker Branch markers
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
index c36ac36f7..6b17d3ee6 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
@@ -24,7 +24,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt config state default-branch - Default branch setting
+wt config state default-branch - Default branch detection and override
Usage: wt config state default-branch [OPTIONS] [COMMAND]
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 03ce1e08b..81e0cfd71 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -29,7 +29,7 @@ The building blocks of wt merge — commit, squash, rebase, push — plu
Usage: wt step [OPTIONS] <COMMAND>
Commands:
- commit Commit changes with LLM commit message
+ commit Stage and commit with LLM-generated message
squash Squash commits since branching
push Fast-forward target to current branch
rebase Rebase onto target
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_short.snap b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
index f0dcd217d..295986224 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
@@ -27,7 +27,7 @@ wt step - Run individual operations
Usage: wt step [OPTIONS] <COMMAND>
Commands:
- commit Commit changes with LLM commit message
+ commit Stage and commit with LLM-generated message
squash Squash commits since branching
push Fast-forward target to current branch
rebase Rebase onto target