Skip to content

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

docs: remove redundant after_long_help openers in step subcommands (#1737)

Maximilian Roos848f83a7a08e
diff --git a/CLAUDE.md b/CLAUDE.md
index ef37c0dd7..1402a17d6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -140,6 +140,16 @@ Documentation has three categories:
3. **Skill-only files** (shell-integration.md, troubleshooting.md):
Edit `skills/worktrunk/reference/` directly — no docs equivalent.
+### Help text authoring
+
+Help text renders in three contexts — check all three when editing:
+
+1. **Terminal** (`wt step X --help`): `about` and `subtitle` appear at the top, `after_long_help` appears below the Options block — separated by distance.
+2. **Web docs** (`docs/content/`): `combine_command_docs()` concatenates `about` + optional `subtitle` + `after_long_help` — they appear as consecutive paragraphs.
+3. **Skill reference** (`skills/worktrunk/reference/`): mirrors web docs.
+
+Because web docs concatenate everything, the `after_long_help` opener must not restate the `about`/`subtitle`. Start with new information — examples, context, or details not already in the definition.
+
After any doc changes, run tests to sync:
```bash
diff --git a/docs/content/step.md b/docs/content/step.md
index 06e250854..02541fd6f 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -92,7 +92,7 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
Stage and commit with LLM-generated message.
-Stages all changes (including untracked files) and commits with an [LLM-generated message](@/llm-commits.md).
+See [LLM-generated commit messages](@/llm-commits.md) for configuration and prompt customization.
### Options
@@ -176,7 +176,7 @@ Usage: <b><span class=c>wt step commit</span></b> <span class=c>[OPTIONS]</span>
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).
+See [LLM-generated commit messages](@/llm-commits.md) for configuration and prompt customization.
### Options
@@ -331,8 +331,6 @@ Usage: <b><span class=c>wt step diff</span></b> <span class=c>[OPTIONS]</span> <
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.
-
### Setup
Add to the project config:
@@ -464,9 +462,7 @@ Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]<
Evaluate a template expression. Prints the result to stdout for use in scripts and shell substitutions.
-Evaluates a template expression in the current worktree context and prints the result to stdout. All [hook template variables and filters](@/hook.md#template-variables) are available.
-
-Output goes to stdout with no decoration, making it suitable for shell substitution and piping.
+All [hook template variables and filters](@/hook.md#template-variables) are available.
### Examples
@@ -544,9 +540,7 @@ Usage: <b><span class=c>wt step eval</span></b> <span class=c>[OPTIONS]</span> <
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.
-
-Context JSON is piped to stdin for scripts that need structured data.
+A summary of successes and failures is shown at the end. Context JSON is piped to stdin for scripts that need structured data.
### Template variables
@@ -756,8 +750,6 @@ Usage: <b><span class=c>wt step prune</span></b> <span class=c>[OPTIONS]</span>
Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.
-Moves worktrees to match the configured `worktree-path` template.
-
### Examples
Preview what would be moved:
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 1198ac2a1..191deca24 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -76,7 +76,7 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
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/).
+See [LLM-generated commit messages](https://worktrunk.dev/llm-commits/) for configuration and prompt customization.
### Options
@@ -158,7 +158,7 @@ Usage: <b><span class=c>wt step commit</span></b> <span class=c>[OPTIONS]</span>
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/).
+See [LLM-generated commit messages](https://worktrunk.dev/llm-commits/) for configuration and prompt customization.
### Options
@@ -309,8 +309,6 @@ Usage: <b><span class=c>wt step diff</span></b> <span class=c>[OPTIONS]</span> <
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.
-
### Setup
Add to the project config:
@@ -440,9 +438,7 @@ Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]<
Evaluate a template expression. Prints the result to stdout for use in scripts and shell substitutions.
-Evaluates a template expression in the current worktree context and prints the result to stdout. All [hook template variables and filters](https://worktrunk.dev/hook/#template-variables) are available.
-
-Output goes to stdout with no decoration, making it suitable for shell substitution and piping.
+All [hook template variables and filters](https://worktrunk.dev/hook/#template-variables) are available.
### Examples
@@ -518,9 +514,7 @@ Usage: <b><span class=c>wt step eval</span></b> <span class=c>[OPTIONS]</span> <
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.
-
-Context JSON is piped to stdin for scripts that need structured data.
+A summary of successes and failures is shown at the end. Context JSON is piped to stdin for scripts that need structured data.
### Template variables
@@ -724,8 +718,6 @@ Usage: <b><span class=c>wt step prune</span></b> <span class=c>[OPTIONS]</span>
Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.
-Moves worktrees to match the configured `worktree-path` template.
-
### Examples
Preview what would be moved:
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 7fe937fdf..2a59ad482 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -6,7 +6,7 @@ use clap::Subcommand;
pub enum StepCommand {
/// 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).
+ after_long_help = r#"See [LLM-generated commit messages](@/llm-commits.md) for configuration and prompt customization.
## Options
@@ -68,7 +68,7 @@ wt step commit --show-prompt | llm -m gpt-5-nano
///
/// 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).
+ after_long_help = r#"See [LLM-generated commit messages](@/llm-commits.md) for configuration and prompt customization.
## Options
@@ -228,10 +228,7 @@ GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default
/// Copy gitignored files to another worktree
///
/// 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.
-
-## Setup
+ #[command(after_long_help = r#"## Setup
Add to the project config:
@@ -317,8 +314,7 @@ The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://c
- worktrunk copies all gitignored files by default; Claude Code requires `.worktreeinclude`
- worktrunk uses copy-on-write for large directories like `target/` — potentially 30x faster on macOS, 6x on Linux
- worktrunk runs as a configurable hook in the worktree lifecycle
-"#
- )]
+"#)]
CopyIgnored {
/// Source worktree branch
///
@@ -345,9 +341,7 @@ The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://c
///
/// Prints the result to stdout for use in scripts and shell substitutions.
#[command(
- after_long_help = r#"Evaluates a template expression in the current worktree context and prints the result to stdout. All [hook template variables and filters](@/hook.md#template-variables) are available.
-
-Output goes to stdout with no decoration, making it suitable for shell substitution and piping.
+ after_long_help = r#"All [hook template variables and filters](@/hook.md#template-variables) are available.
## Examples
@@ -404,9 +398,7 @@ Note: This command is experimental and may change in future versions.
///
/// 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.
-
-Context JSON is piped to stdin for scripts that need structured data.
+ after_long_help = r#"A summary of successes and failures is shown at the end. Context JSON is piped to stdin for scripts that need structured data.
## Template variables
@@ -553,10 +545,7 @@ wt step prune
/// \[experimental\] Move worktrees to expected paths
///
/// Relocates worktrees whose path doesn't match the `worktree-path` template.
- #[command(
- after_long_help = r#"Moves worktrees to match the configured `worktree-path` template.
-
-## Examples
+ #[command(after_long_help = r#"## Examples
Preview what would be moved:
@@ -607,8 +596,7 @@ expected path. Untracked and gitignored files remain at the original location.
- **Detached HEAD** — no branch to compute expected path
Note: This command is experimental and may change in future versions.
-"#
- )]
+"#)]
Relocate {
/// Worktrees to relocate (defaults to all mismatched)
#[arg(add = crate::completion::worktree_only_completer())]