Skip to content

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

docs(step): move --stage docs to commit/squash subcommands (#625)

Maximilian Roosaec572ef8b2f
diff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/.claude-plugin/skills/worktrunk/reference/step.md
index 0d83b9f43..5299d1971 100644
--- a/.claude-plugin/skills/worktrunk/reference/step.md
+++ b/.claude-plugin/skills/worktrunk/reference/step.md
@@ -28,11 +28,43 @@ wt step push
- `copy-ignored` — Copy gitignored files between worktrees
- `for-each` — [experimental] Run a command in every worktree
-## Options
+## Command reference
+
+wt step - Run individual operations
+
+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>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
+ <b><span class=c>copy-ignored</span></b> Copy gitignored files to another worktree
+ <b><span class=c>for-each</span></b> [experimental] Run command in each worktree
+
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
+
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Show debug info (-v), or also write diagnostic report (-vv)
+
+## wt step commit
+
+Stages all changes (including untracked files) and commits with an [LLM-generated message](https://worktrunk.dev/llm-commits/).
+
+### Options
-### `--stage`
+#### `--stage`
-Controls what to stage before committing. Available for `commit` and `squash`:
+Controls what to stage before committing:
| Value | Behavior |
|-------|----------|
@@ -42,7 +74,6 @@ Controls what to stage before committing. Available for `commit` and `squash`:
```bash
wt step commit --stage=tracked
-wt step squash --stage=none
```
Configure the default in user config:
@@ -52,7 +83,7 @@ Configure the default in user config:
stage = "tracked"
```
-### `--show-prompt`
+#### `--show-prompt`
Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
@@ -64,21 +95,119 @@ wt step commit --show-prompt | less
wt step commit --show-prompt | llm -m gpt-5-nano
```
-## Command reference
+### Command reference
-wt step - Run individual operations
+wt step commit - Commit changes with LLM commit message
-Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
+Stages working tree changes and commits with an LLM-generated message.
-<b><span class=g>Commands:</span></b>
- <b><span class=c>commit</span></b> Commit changes with LLM commit 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
- <b><span class=c>copy-ignored</span></b> Copy gitignored files to another worktree
- <b><span class=c>for-each</span></b> [experimental] Run command in each worktree
+Usage: <b><span class=c>wt step commit</span></b> <span class=c>[OPTIONS]</span>
<b><span class=g>Options:</span></b>
+ <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>
+ Skip approval prompts
+
+ <b><span class=c>--no-verify</span></b>
+ Skip hooks
+
+ <b><span class=c>--stage</span></b><span class=c> &lt;STAGE&gt;</span>
+ What to stage before committing [default: all]
+
+ Possible values:
+ - <b><span class=c>all</span></b>: Stage everything: untracked files + unstaged tracked
+ changes
+ - <b><span class=c>tracked</span></b>: Stage tracked changes only (like <b>git add -u</b>)
+ - <b><span class=c>none</span></b>: Stage nothing, commit only what&#39;s already in the index
+
+ <b><span class=c>--show-prompt</span></b>
+ Show prompt without running LLM
+
+ Outputs the rendered prompt to stdout for debugging or manual piping.
+
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
+
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Show debug info (-v), or also write diagnostic report (-vv)
+
+## wt step squash
+
+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/).
+
+### Options
+
+#### `--stage`
+
+Controls what to stage before squashing:
+
+| Value | Behavior |
+|-------|----------|
+| `all` | Stage all changes including untracked files (default) |
+| `tracked` | Stage only modified tracked files |
+| `none` | Don't stage anything, squash only committed changes |
+
+```bash
+wt step squash --stage=none
+```
+
+Configure the default in user config:
+
+```toml
+[commit]
+stage = "tracked"
+```
+
+#### `--show-prompt`
+
+Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
+
+```bash
+wt step squash --show-prompt | less
+```
+
+### Command reference
+
+wt step squash - Squash commits since branching
+
+Stages working tree changes, squashes all commits since diverging from target
+into one, generates message with LLM.
+
+Usage: <b><span class=c>wt step squash</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>
+
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[TARGET]</span>
+ Target branch
+
+ Defaults to default branch.
+
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>
+ Skip approval prompts
+
+ <b><span class=c>--no-verify</span></b>
+ Skip hooks
+
+ <b><span class=c>--stage</span></b><span class=c> &lt;STAGE&gt;</span>
+ What to stage before committing [default: all]
+
+ Possible values:
+ - <b><span class=c>all</span></b>: Stage everything: untracked files + unstaged tracked
+ changes
+ - <b><span class=c>tracked</span></b>: Stage tracked changes only (like <b>git add -u</b>)
+ - <b><span class=c>none</span></b>: Stage nothing, commit only what&#39;s already in the index
+
+ <b><span class=c>--show-prompt</span></b>
+ Show prompt without running LLM
+
+ Outputs the rendered prompt to stdout for debugging or manual piping.
+
<b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
Print help (see a summary with &#39;-h&#39;)
diff --git a/docs/content/step.md b/docs/content/step.md
index b3fff553d..e2704769d 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -36,11 +36,50 @@ wt step push
- `copy-ignored` — Copy gitignored files between worktrees
- `for-each` — [experimental] Run a command in every worktree
-## Options
+## See also
+
+- [`wt merge`](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
+- [`wt hook`](@/hook.md) — Run configured hooks
-### `--stage`
+## Command reference
-Controls what to stage before committing. Available for `commit` and `squash`:
+{% terminal() %}
+wt step - Run individual operations
+
+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>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
+ <b><span class=c>copy-ignored</span></b> Copy gitignored files to another worktree
+ <b><span class=c>for-each</span></b> [experimental] Run command in each worktree
+
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
+
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Show debug info (-v), or also write diagnostic report (-vv)
+{% end %}
+
+## wt step commit
+
+Stages all changes (including untracked files) and commits with an [LLM-generated message](@/llm-commits.md).
+
+### Options
+
+#### `--stage`
+
+Controls what to stage before committing:
| Value | Behavior |
|-------|----------|
@@ -50,7 +89,6 @@ Controls what to stage before committing. Available for `commit` and `squash`:
```bash
wt step commit --stage=tracked
-wt step squash --stage=none
```
Configure the default in user config:
@@ -60,7 +98,7 @@ Configure the default in user config:
stage = "tracked"
```
-### `--show-prompt`
+#### `--show-prompt`
Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
@@ -72,27 +110,122 @@ wt step commit --show-prompt | less
wt step commit --show-prompt | llm -m gpt-5-nano
```
-## See also
+### Command reference
-- [`wt merge`](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
-- [`wt hook`](@/hook.md) — Run configured hooks
+{% terminal() %}
+wt step commit - Commit changes with LLM commit message
-## Command reference
+Stages working tree changes and commits with an LLM-generated message.
+
+Usage: <b><span class=c>wt step commit</span></b> <span class=c>[OPTIONS]</span>
+
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>
+ Skip approval prompts
+
+ <b><span class=c>--no-verify</span></b>
+ Skip hooks
+
+ <b><span class=c>--stage</span></b><span class=c> &lt;STAGE&gt;</span>
+ What to stage before committing [default: all]
+
+ Possible values:
+ - <b><span class=c>all</span></b>: Stage everything: untracked files + unstaged tracked
+ changes
+ - <b><span class=c>tracked</span></b>: Stage tracked changes only (like <b>git add -u</b>)
+ - <b><span class=c>none</span></b>: Stage nothing, commit only what&#39;s already in the index
+
+ <b><span class=c>--show-prompt</span></b>
+ Show prompt without running LLM
+
+ Outputs the rendered prompt to stdout for debugging or manual piping.
+
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
+
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Show debug info (-v), or also write diagnostic report (-vv)
+{% end %}
+
+## wt step squash
+
+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).
+
+### Options
+
+#### `--stage`
+
+Controls what to stage before squashing:
+
+| Value | Behavior |
+|-------|----------|
+| `all` | Stage all changes including untracked files (default) |
+| `tracked` | Stage only modified tracked files |
+| `none` | Don't stage anything, squash only committed changes |
+
+```bash
+wt step squash --stage=none
+```
+
+Configure the default in user config:
+
+```toml
+[commit]
+stage = "tracked"
+```
+
+#### `--show-prompt`
+
+Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
+
+```bash
+wt step squash --show-prompt | less
+```
+
+### Command reference
{% terminal() %}
-wt step - Run individual operations
+wt step squash - Squash commits since branching
-Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
+Stages working tree changes, squashes all commits since diverging from target
+into one, generates message with LLM.
-<b><span class=g>Commands:</span></b>
- <b><span class=c>commit</span></b> Commit changes with LLM commit 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
- <b><span class=c>copy-ignored</span></b> Copy gitignored files to another worktree
- <b><span class=c>for-each</span></b> [experimental] Run command in each worktree
+Usage: <b><span class=c>wt step squash</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>
+
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[TARGET]</span>
+ Target branch
+
+ Defaults to default branch.
<b><span class=g>Options:</span></b>
+ <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>
+ Skip approval prompts
+
+ <b><span class=c>--no-verify</span></b>
+ Skip hooks
+
+ <b><span class=c>--stage</span></b><span class=c> &lt;STAGE&gt;</span>
+ What to stage before committing [default: all]
+
+ Possible values:
+ - <b><span class=c>all</span></b>: Stage everything: untracked files + unstaged tracked
+ changes
+ - <b><span class=c>tracked</span></b>: Stage tracked changes only (like <b>git add -u</b>)
+ - <b><span class=c>none</span></b>: Stage nothing, commit only what&#39;s already in the index
+
+ <b><span class=c>--show-prompt</span></b>
+ Show prompt without running LLM
+
+ Outputs the rendered prompt to stdout for debugging or manual piping.
+
<b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
Print help (see a summary with &#39;-h&#39;)
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 95ae3ca4a..8fd412c7e 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -982,46 +982,12 @@ wt step push
- `copy-ignored` — Copy gitignored files between worktrees
- `for-each` — [experimental] Run a command in every worktree
-## Options
-
-### `--stage`
-
-Controls what to stage before committing. Available for `commit` and `squash`:
-
-| Value | Behavior |
-|-------|----------|
-| `all` | Stage all changes including untracked files (default) |
-| `tracked` | Stage only modified tracked files |
-| `none` | Don't stage anything, commit only what's already staged |
-
-```bash
-wt step commit --stage=tracked
-wt step squash --stage=none
-```
-
-Configure the default in user config:
-
-```toml
-[commit]
-stage = "tracked"
-```
-
-### `--show-prompt`
-
-Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
-
-```bash
-# Inspect the rendered prompt
-wt step commit --show-prompt | less
-
-# Pipe to a different LLM
-wt step commit --show-prompt | llm -m gpt-5-nano
-```
-
## See also
- [`wt merge`](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
- [`wt hook`](@/hook.md) — Run configured hooks
+<!-- subdoc: commit -->
+<!-- subdoc: squash -->
<!-- subdoc: copy-ignored -->
<!-- subdoc: for-each -->"#
)]
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 9a87c9d16..ff49ed5b4 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -6,6 +6,45 @@ pub enum StepCommand {
/// Commit changes with LLM commit message
///
/// Stages working tree changes and commits with an LLM-generated message.
+ #[command(
+ after_long_help = r#"Stages all changes (including untracked files) and commits with an [LLM-generated message](@/llm-commits.md).
+
+## Options
+
+### `--stage`
+
+Controls what to stage before committing:
+
+| Value | Behavior |
+|-------|----------|
+| `all` | Stage all changes including untracked files (default) |
+| `tracked` | Stage only modified tracked files |
+| `none` | Don't stage anything, commit only what's already staged |
+
+```console
+wt step commit --stage=tracked
+```
+
+Configure the default in user config:
+
+```toml
+[commit]
+stage = "tracked"
+```
+
+### `--show-prompt`
+
+Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
+
+```console
+# Inspect the rendered prompt
+wt step commit --show-prompt | less
+
+# Pipe to a different LLM
+wt step commit --show-prompt | llm -m gpt-5-nano
+```
+"#
+ )]
Commit {
/// Skip approval prompts
#[arg(short, long)]
@@ -29,6 +68,41 @@ pub enum StepCommand {
/// Squash commits since branching
///
/// Stages working tree changes, squashes all commits since diverging from target into one, 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).
+
+## Options
+
+### `--stage`
+
+Controls what to stage before squashing:
+
+| Value | Behavior |
+|-------|----------|
+| `all` | Stage all changes including untracked files (default) |
+| `tracked` | Stage only modified tracked files |
+| `none` | Don't stage anything, squash only committed changes |
+
+```console
+wt step squash --stage=none
+```
+
+Configure the default in user config:
+
+```toml
+[commit]
+stage = "tracked"
+```
+
+### `--show-prompt`
+
+Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
+
+```console
+wt step squash --show-prompt | less
+```
+"#
+ )]
Squash {
/// Target branch
///
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 83de59791..430372df9 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -70,36 +70,6 @@ Manual merge workflow with review between steps:
- copy-ignored — Copy gitignored files between worktrees
- for-each — [experimental] Run a command in every worktree
-Options
-
-`--stage`
-
-Controls what to stage before committing. Available for commit and squash:
-
- Value Behavior
- ─────── ───────────────────────────────────────────────────────
- all Stage all changes including untracked files (default)
- tracked Stage only modified tracked files
- none Don't stage anything, commit only what's already staged
-
- wt step commit --stage=tracked
- wt step squash --stage=none
-
-Configure the default in user config:
-
- [commit]
- stage = "tracked"
-
-`--show-prompt`
-
-Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
-
- # Inspect the rendered prompt
- wt step commit --show-prompt | less
- 
- # Pipe to a different LLM
- wt step commit --show-prompt | llm -m gpt-5-nano
-
See also
- wt merge — Runs commit → squash → rebase → hooks → push → cleanup automatically