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.mdindex 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 loggeddiff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.mdindex 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.### Examplesdiff --git a/.claude-plugin/skills/worktrunk/reference/list.md b/.claude-plugin/skills/worktrunk/reference/list.mdindex 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.mdindex 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://cwt 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.mdindex 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 loggeddiff --git a/docs/content/hook.md b/docs/content/hook.mdindex 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.### Examplesdiff --git a/docs/content/list.md b/docs/content/list.mdindex 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.mdindex 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.rsindex 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.rsindex 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 firstlet 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 placeholderlet subdoc_marker = "<!-- subdoc:";@@ -443,6 +414,45 @@ fn expand_subdoc_placeholders(text: &str, parent_cmd: &clap::Command, parent_namresult}+/// 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 subdocslet subdoc_marker = "<!-- subdoc:";