Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Reorganize config and hook documentation to place command references before nested subdocs
Maximilian Roosfaf56e45ae51
diff --git a/docs/content/config.md b/docs/content/config.mdindex 042679109..abbd5eb77 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -229,6 +229,34 @@ WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \| `NO_COLOR` | Disable colored output ([standard](https://no-color.org/)) || `CLICOLOR_FORCE` | Force colored output even when not a TTY |+## Command reference++```+wt config - Manage configuration and shell integration++Usage: wt config [OPTIONS] <COMMAND>++Commands:+ shell Shell integration setup+ create Create configuration file+ show Show configuration files & locations+ state Get, set, or clear stored state++Options:+ -h, --help+ Print help (see a summary with '-h')++Global Options:+ -C <path>+ Working directory for this command++ --config <path>+ User config file path++ -v, --verbose+ Show commands and debug info+```+## wt config create### User config@@ -612,6 +640,37 @@ Clear all stored state:wt config state clear```+### Command reference++```+wt config state - Get, set, or clear stored state++Usage: wt config state [OPTIONS] <COMMAND>++Commands:+ default-branch Default branch setting+ previous-branch Previous branch (for wt switch -)+ ci-status CI status cache+ marker Branch markers+ logs Background operation logs+ get Get all stored state+ clear Clear all stored state++Options:+ -h, --help+ Print help (see a summary with '-h')++Global Options:+ -C <path>+ Working directory for this command++ --config <path>+ User config file path++ -v, --verbose+ Show commands and debug info+```+## wt config state default-branch### Detection@@ -852,63 +911,4 @@ Global Options:Show commands and debug info```-### Command reference--```-wt config state - Get, set, or clear stored state--Usage: wt config state [OPTIONS] <COMMAND>--Commands:- default-branch Default branch setting- previous-branch Previous branch (for wt switch -)- ci-status CI status cache- marker Branch markers- logs Background operation logs- get Get all stored state- clear Clear all stored state--Options:- -h, --help- Print help (see a summary with '-h')--Global Options:- -C <path>- Working directory for this command-- --config <path>- User config file path-- -v, --verbose- Show commands and debug info-```--## Command reference--```-wt config - Manage configuration and shell integration--Usage: wt config [OPTIONS] <COMMAND>--Commands:- shell Shell integration setup- create Create configuration file- show Show configuration files & locations- state Get, set, or clear stored state--Options:- -h, --help- Print help (see a summary with '-h')--Global Options:- -C <path>- Working directory for this command-- --config <path>- User config file path-- -v, --verbose- Show commands and debug info-```-<!-- END AUTO-GENERATED from `wt config --help-page` -->diff --git a/docs/content/hook.md b/docs/content/hook.mdindex ead44f847..c24176441 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -375,4 +375,68 @@ Global Options:Show commands and debug info```+## wt hook approvals++### How Approvals Work++Commands from project hooks (`.config/wt.toml`) and LLM configuration require+approval on first run. This prevents untrusted projects from running arbitrary+commands.++**Approval flow:**+1. Command is shown with expanded template variables+2. User approves or denies+3. Approved commands are saved to user config under `[projects."project-id"]`++**When re-approval is required:**+- Command template changes (not just variable values)+- Project ID changes (repository moves)++**Bypassing prompts:**+- `--force` flag on individual commands (e.g., `wt merge --force`)+- Useful for CI/automation where prompts aren't possible++### Examples++Pre-approve all commands for current project:+```bash+wt hook approvals add+```++Clear approvals for current project:+```bash+wt hook approvals clear+```++Clear global approvals:+```bash+wt hook approvals clear --global+```++### Command reference++```+wt hook approvals - Manage command approvals++Usage: wt hook approvals [OPTIONS] <COMMAND>++Commands:+ add Store approvals in config+ clear Clear approved commands from config++Options:+ -h, --help+ Print help (see a summary with '-h')++Global Options:+ -C <path>+ Working directory for this command++ --config <path>+ User config file path++ -v, --verbose+ Show commands and debug info+```+<!-- END AUTO-GENERATED from `wt hook --help-page` -->diff --git a/docs/content/step.md b/docs/content/step.mdindex b32c46cfa..856be2665 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -70,4 +70,82 @@ Global Options:Show commands and debug info```+## wt step for-each++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.++### Template variables++All variables are shell-escaped:++| Variable | Description |+|----------|-------------|+| `{{ branch }}` | Branch name (slashes replaced with dashes) |+| `{{ worktree }}` | Absolute path to the worktree |+| `{{ worktree_name }}` | Worktree directory name |+| `{{ repo }}` | Repository name |+| `{{ repo_root }}` | Absolute path to the main repository root |+| `{{ commit }}` | Current HEAD commit SHA (full) |+| `{{ short_commit }}` | Current HEAD commit SHA (7 chars) |+| `{{ default_branch }}` | Default branch name (e.g., "main") |+| `{{ remote }}` | Primary remote name (e.g., "origin") |+| `{{ remote_url }}` | Primary remote URL |+| `{{ upstream }}` | Upstream tracking branch, if configured |++### Examples++Check status across all worktrees:++```bash+wt step for-each -- git status --short+```++Run npm install in all worktrees:++```bash+wt step for-each -- npm install+```++Use branch name in command:++```bash+wt step for-each -- "echo Branch: {{ branch }}"+```++Pull updates in worktrees with upstreams (skips others):++```bash+git fetch --prune && wt step for-each -- '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'+```++Note: This command is experimental and may change in future versions.++### Command reference++```+wt step for-each - [experimental] Run command in each worktree++Usage: wt step for-each [OPTIONS] -- <ARGS>...++Arguments:+ <ARGS>...+ Command template (see --help for all variables)++Options:+ -h, --help+ Print help (see a summary with '-h')++Global Options:+ -C <path>+ Working directory for this command++ --config <path>+ User config file path++ -v, --verbose+ Show commands and debug info+```+<!-- END AUTO-GENERATED from `wt step --help-page` -->diff --git a/src/cli.rs b/src/cli.rsindex 535f0557e..c11ecc453 100644--- a/src/cli.rs+++ b/src/cli.rs@@ -1412,6 +1412,8 @@ wt step push- [wt merge](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically- [wt hook](@/hook.md) — Run hooks independently++<!-- subdoc: for-each -->"#)]Step {@@ -1756,6 +1758,8 @@ env = "cp {{ repo_root }}/.env.local .env"- [wt merge](@/merge.md) — Runs hooks automatically during merge- [wt switch](@/switch.md) — Runs post-create/post-start hooks on `--create`- [wt config](@/config.md) — Manage hook approvals++<!-- subdoc: approvals -->"#)]Hook {diff --git a/src/main.rs b/src/main.rsindex 13a0359e0..25d19413e 100644--- a/src/main.rs+++ b/src/main.rs@@ -277,18 +277,29 @@ fn handle_help_page(args: &[String]) {};// Get the after_long_help content- // Transform for web docs: console→bash, status colors, demo images, subdocs+ // 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 after_help = sub+ let raw_help = sub.get_after_long_help()- .map(|s| {- let text = s.to_string().replace("```console\n", "```bash\n");- let text = expand_demo_placeholders(&text);- let text = expand_subdoc_placeholders(&text, sub, &parent_name);- colorize_ci_status_for_html(&text)- })+ .map(|s| s.to_string()).unwrap_or_default();+ // Split content at first subdoc placeholder+ let subdoc_marker = "<!-- subdoc:";+ let (main_content, subdoc_content) = if let Some(pos) = raw_help.find(subdoc_marker) {+ (&raw_help[..pos], Some(&raw_help[pos..]))+ } else {+ (raw_help.as_str(), None)+ };++ // Process main content (before subdocs)+ let main_help = {+ let text = main_content.replace("```console\n", "```bash\n");+ let text = expand_demo_placeholders(&text);+ colorize_ci_status_for_html(&text)+ };+// Get the help reference blocklet reference_block = get_help_reference(&[subcommand]);@@ -299,14 +310,25 @@ fn handle_help_page(args: &[String]) {"<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->");println!();- println!("{}", after_help.trim());+ println!("{}", main_help.trim());println!();++ // Main command reference immediately after its contentprintln!("## Command reference");println!();println!("```");print!("{}", reference_block.trim());println!();println!("```");++ // Subdocs follow, each with their own command reference at the end+ if let Some(subdocs) = subdoc_content {+ let subdocs_expanded = expand_subdoc_placeholders(subdocs, sub, &parent_name);+ let subdocs_processed = colorize_ci_status_for_html(&subdocs_expanded);+ println!();+ println!("{}", subdocs_processed.trim());+ }+println!();println!("<!-- END AUTO-GENERATED from `wt {subcommand} --help-page` -->");}@@ -405,7 +427,8 @@ fn expand_subdoc_placeholders(text: &str, parent_cmd: &clap::Command, parent_nam/// Format a subcommand as an H2 section for docs.////// Includes the subcommand's `after_long_help` (conceptual docs) followed by-/// the command reference (usage, options).+/// the command reference (usage, options). If the subdoc has nested subdocs,+/// the command reference comes before them.fn format_subcommand_section(sub: &clap::Command,parent_name: &str,@@ -415,26 +438,26 @@ fn format_subcommand_section(// full_command is "wt config create"let full_command = format!("{} {}", parent_name, subcommand_name);- // Get the after_long_help content (conceptual docs)- // First increase heading levels for the direct content, THEN expand subdocs.- // This way subdocs stay at their written level (##) instead of being bumped up.- let after_help = sub+ // Get the raw after_long_help content+ let raw_help = sub.get_after_long_help()- .map(|s| {- let text = s.to_string().replace("```console\n", "```bash\n");- let text = increase_heading_levels(&text);- let text = expand_subdoc_placeholders(&text, sub, &full_command);- colorize_ci_status_for_html(&text)- })+ .map(|s| s.to_string()).unwrap_or_default();- // Format the section- let mut section = format!("## {}\n\n", full_command);+ // Split content at first subdoc placeholder so command reference comes before nested subdocs+ let subdoc_marker = "<!-- subdoc:";+ let (main_content, subdoc_content) = if let Some(pos) = raw_help.find(subdoc_marker) {+ (&raw_help[..pos], Some(&raw_help[pos..]))+ } else {+ (raw_help.as_str(), None)+ };- if !after_help.is_empty() {- section.push_str(after_help.trim());- section.push_str("\n\n");- }+ // Process main content (before any nested subdocs)+ let main_help = {+ let text = main_content.replace("```console\n", "```bash\n");+ let text = increase_heading_levels(&text);+ colorize_ci_status_for_html(&text)+ };// Build command path from parent_name: "wt config" -> ["config", "create"]let command_path: Vec<&str> = parent_name@@ -446,10 +469,28 @@ fn format_subcommand_section(let reference_block = get_help_reference(&command_path);+ // Format the section: heading, main content, command reference, then nested subdocs+ let mut section = format!("## {}\n\n", full_command);++ if !main_help.is_empty() {+ section.push_str(main_help.trim());+ section.push_str("\n\n");+ }++ // Command reference comes after main content but before nested subdocssection.push_str("### Command reference\n\n```\n");section.push_str(reference_block.trim());section.push_str("\n```\n");+ // Expand nested subdocs after the command reference+ if let Some(subdocs) = subdoc_content {+ let subdocs_expanded = expand_subdoc_placeholders(subdocs, sub, &full_command);+ let subdocs_processed = colorize_ci_status_for_html(&subdocs_expanded);+ section.push('\n');+ section.push_str(subdocs_processed.trim());+ section.push('\n');+ }+section}