Skip to content

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.md
index 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.md
index 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.md
index 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.rs
index 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.rs
index 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 first
let 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 block
let 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 content
println!("## 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 subdocs
section.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
}