Skip to content

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

fix: include about/long_about in subcommand docs (#793)

Maximilian Roosdc0db6f57dba
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index 30bb1117f..11c3a817b 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -417,6 +417,8 @@ Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <spa
## wt config show
+Show configuration files & locations.
+
Shows location and contents of user config (`~/.config/worktrunk/config.toml`)
and project config (`.config/wt.toml`).
@@ -459,6 +461,8 @@ Usage: <b><span class=c>wt config show</span></b> <span class=c>[OPTIONS]</span>
## wt config state
+Manage internal data and cache.
+
State is stored in `.git/` (config entries and log files), separate from configuration files.
Use `wt config show` to view file-based configuration.
@@ -534,6 +538,8 @@ Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span
## wt config state default-branch
+Default branch setting.
+
Useful in scripts to avoid hardcoding `main` or `master`:
```bash
@@ -586,6 +592,8 @@ Usage: <b><span class=c>wt config state default-branch</span></b> <span class=c>
## wt config state ci-status
+CI status cache.
+
Caches GitHub/GitLab CI status for display in [`wt list`](https://worktrunk.dev/list/#ci-status).
### How it works
@@ -636,6 +644,8 @@ Usage: <b><span class=c>wt config state ci-status</span></b> <span class=c>[OPTI
## wt config state marker
+Branch markers.
+
Custom status text or emoji shown in the `wt list` Status column.
### Display
@@ -692,6 +702,8 @@ Usage: <b><span class=c>wt config state marker</span></b> <span class=c>[OPTIONS
## wt config state logs
+Background operation logs.
+
View and manage logs from background operations.
### What's logged
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.md
index 9c8f48c66..7d4907ff9 100644
--- a/.claude-plugin/skills/worktrunk/reference/hook.md
+++ b/.claude-plugin/skills/worktrunk/reference/hook.md
@@ -1,6 +1,6 @@
# wt hook
-Run configured hooks
+Run configured hooks.
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.
@@ -447,6 +447,8 @@ Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span
## wt hook approvals
+Manage command approvals.
+
Project hooks require approval on first run to prevent untrusted projects from running arbitrary commands.
### Examples
diff --git a/.claude-plugin/skills/worktrunk/reference/list.md b/.claude-plugin/skills/worktrunk/reference/list.md
index 3fa3df3e2..314a2db43 100644
--- a/.claude-plugin/skills/worktrunk/reference/list.md
+++ b/.claude-plugin/skills/worktrunk/reference/list.md
@@ -1,6 +1,6 @@
# wt list
-List worktrees and their status
+List worktrees and their status.
Shows uncommitted changes, divergence from the default branch and remote, and optional CI status.
diff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/.claude-plugin/skills/worktrunk/reference/step.md
index 63cfbb31f..7b48eeb71 100644
--- a/.claude-plugin/skills/worktrunk/reference/step.md
+++ b/.claude-plugin/skills/worktrunk/reference/step.md
@@ -61,6 +61,8 @@ 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.
+
Stages all changes (including untracked files) and commits with an [LLM-generated message](https://worktrunk.dev/llm-commits/).
### Options
@@ -142,6 +144,8 @@ 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.
+
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
@@ -226,6 +230,8 @@ 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.
+
Git worktrees share the repository but not untracked files. This command copies gitignored files to another worktree, eliminating cold starts.
### Setup
@@ -311,10 +317,9 @@ The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://c
wt step copy-ignored - Copy gitignored files to another worktree
-Copies 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.
+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.
Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]</span>
@@ -347,6 +352,8 @@ 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.
+
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.
diff --git a/docs/content/config.md b/docs/content/config.md
index a985a1e99..33dd09e34 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -427,6 +427,8 @@ Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <spa
## wt config show
+Show configuration files & locations.
+
Shows location and contents of user config (`~/.config/worktrunk/config.toml`)
and project config (`.config/wt.toml`).
@@ -471,6 +473,8 @@ Usage: <b><span class=c>wt config show</span></b> <span class=c>[OPTIONS]</span>
## wt config state
+Manage internal data and cache.
+
State is stored in `.git/` (config entries and log files), separate from configuration files.
Use `wt config show` to view file-based configuration.
@@ -548,6 +552,8 @@ Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span
## wt config state default-branch
+Default branch setting.
+
Useful in scripts to avoid hardcoding `main` or `master`:
```bash
@@ -602,6 +608,8 @@ Usage: <b><span class=c>wt config state default-branch</span></b> <span class=c>
## wt config state ci-status
+CI status cache.
+
Caches GitHub/GitLab CI status for display in [`wt list`](@/list.md#ci-status).
### How it works
@@ -654,6 +662,8 @@ Usage: <b><span class=c>wt config state ci-status</span></b> <span class=c>[OPTI
## wt config state marker
+Branch markers.
+
Custom status text or emoji shown in the `wt list` Status column.
### Display
@@ -712,6 +722,8 @@ Usage: <b><span class=c>wt config state marker</span></b> <span class=c>[OPTIONS
## wt config state logs
+Background operation logs.
+
View and manage logs from background operations.
### What's logged
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 982bec6d8..3fda5ff13 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -8,7 +8,7 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt hook --help-page` — edit cli.rs to update -->
-Run configured hooks
+Run configured hooks.
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.
@@ -463,6 +463,8 @@ Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span
## wt hook approvals
+Manage command approvals.
+
Project hooks require approval on first run to prevent untrusted projects from running arbitrary commands.
### Examples
diff --git a/docs/content/list.md b/docs/content/list.md
index 2a677007c..dc4344aa0 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -8,7 +8,7 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt list --help-page` — edit cli.rs to update -->
-List worktrees and their status
+List worktrees and their status.
Shows uncommitted changes, divergence from the default branch and remote, and optional CI status.
diff --git a/docs/content/step.md b/docs/content/step.md
index d998b0814..d13c9706b 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -76,6 +76,8 @@ 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.
+
Stages all changes (including untracked files) and commits with an [LLM-generated message](@/llm-commits.md).
### Options
@@ -159,6 +161,8 @@ 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.
+
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
@@ -245,6 +249,8 @@ 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.
+
Git worktrees share the repository but not untracked files. This command copies gitignored files to another worktree, eliminating cold starts.
### Setup
@@ -331,10 +337,9 @@ The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://c
{% terminal() %}
wt step copy-ignored - Copy gitignored files to another worktree
-Copies 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.
+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.
Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]</span>
@@ -368,6 +373,8 @@ 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.
+
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.
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 38e322dd7..d8d4e8b89 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -153,10 +153,9 @@ wt step squash --show-prompt | less
/// Copy gitignored files to another worktree
///
- /// Copies 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.
+ /// 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.
#[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.
diff --git a/src/help.rs b/src/help.rs
index d4ee1aa8b..28e1db60b 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -258,40 +258,11 @@ Commands with pages: merge, switch, remove, list"
return;
};
- // Get the long_about (subtitle) and after_long_help content
+ // Get combined docs: about + subtitle + after_long_help
// Transform for web docs: console→bash, status colors, demo images
// Subdocs are expanded separately so main Command reference comes first
let parent_name = format!("wt {}", subcommand);
- let about = sub.get_about().map(|s| s.to_string());
- let long_about = sub.get_long_about().map(|s| s.to_string());
- let after_long_help = sub
- .get_after_long_help()
- .map(|s| s.to_string())
- .unwrap_or_default();
-
- // Extract subtitle: the part of long_about beyond the short about
- // Doc comments produce: "Short about\n\nLong description" in long_about
- // We only want the long description part (subtitle) for web docs
- let subtitle = match (&about, &long_about) {
- (Some(short), Some(long)) if long.starts_with(short) => {
- let rest = long[short.len()..].trim_start();
- if rest.is_empty() {
- None
- } else {
- Some(rest.to_string())
- }
- }
- _ => None,
- };
-
- // 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,
- };
+ let raw_help = combine_command_docs(sub);
// Split content at first subdoc placeholder
let subdoc_marker = "<!-- subdoc:";
@@ -443,6 +414,45 @@ fn expand_subdoc_placeholders(text: &str, parent_cmd: &clap::Command, parent_nam
result
}
+/// Combine a command's about, long_about, and after_long_help into documentation content.
+///
+/// The pattern is: `"definition. subtitle\n\n<after_long_help>"`
+/// - `about` is the one-liner definition
+/// - `subtitle` is the extra content in `long_about` beyond the `about`
+/// - If `long_about` doesn't extend `about`, subtitle is empty
+fn combine_command_docs(cmd: &clap::Command) -> String {
+ let about = cmd.get_about().map(|s| s.to_string());
+ let long_about = cmd.get_long_about().map(|s| s.to_string());
+ let after_long_help = cmd
+ .get_after_long_help()
+ .map(|s| s.to_string())
+ .unwrap_or_default();
+
+ // Extract subtitle: the part of long_about beyond the short about
+ // Doc comments produce: "Short about\n\nLong description" in long_about
+ // We only want the long description part (subtitle) for web docs
+ let subtitle = match (&about, &long_about) {
+ (Some(short), Some(long)) if long.starts_with(short) => {
+ let rest = long[short.len()..].trim_start();
+ if rest.is_empty() {
+ None
+ } else {
+ Some(rest.to_string())
+ }
+ }
+ _ => None,
+ };
+
+ // Combine: definition + subtitle as single lead paragraph, then after_long_help
+ // Definition doesn't have trailing period, subtitle does, so join with ". "
+ 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,
+ }
+}
+
/// Format a subcommand as an H2 section for docs.
///
/// Includes the subcommand's `after_long_help` (conceptual docs) followed by
@@ -457,11 +467,8 @@ fn format_subcommand_section(
// full_command is "wt config create"
let full_command = format!("{} {}", parent_name, subcommand_name);
- // Get the raw after_long_help content
- let raw_help = sub
- .get_after_long_help()
- .map(|s| s.to_string())
- .unwrap_or_default();
+ // Get combined docs: about + subtitle + after_long_help
+ let raw_help = combine_command_docs(sub);
// Split content at first subdoc placeholder so command reference comes before nested subdocs
let subdoc_marker = "<!-- subdoc:";