Skip to content

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

Add colored command reference output to documentation (#273)

Maximilian Roos710b881df046
diff --git a/default_16038749127235320115_0_42549.profraw b/default_16038749127235320115_0_42549.profraw
deleted file mode 100644
index b4f78252e..000000000
Binary files a/default_16038749127235320115_0_42549.profraw and /dev/null differ
diff --git a/default_16038749127235320115_0_88478.profraw b/default_16038749127235320115_0_88478.profraw
deleted file mode 100644
index e4fd948e3..000000000
Binary files a/default_16038749127235320115_0_88478.profraw and /dev/null differ
diff --git a/default_16038749127235320115_0_98828.profraw b/default_16038749127235320115_0_98828.profraw
deleted file mode 100644
index 5108f5789..000000000
Binary files a/default_16038749127235320115_0_98828.profraw and /dev/null differ
diff --git a/dev/config.example.toml b/dev/config.example.toml
index bc82996d6..2ab8bbb1d 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -71,7 +71,7 @@ approved-commands = ["npm install"]
# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),
# use a separate PROJECT config file at <repo>/.config/wt.toml
-# Run `wt config create --project` to create one, or see https://worktrunk.dev/hooks/
+# Run `wt config create --project` to create one, or see https://worktrunk.dev/hook/
# ============================================================================
# Custom Prompt Templates (Advanced)
diff --git a/docs/content/config.md b/docs/content/config.md
index 4f11c6209..53c8a2342 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -236,31 +236,31 @@ WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \
## Command reference
-```
+{% terminal() %}
wt config - Manage configuration and shell integration
-Usage: wt config [OPTIONS] <COMMAND>
+Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
-Commands:
- shell Shell integration setup
- create Create configuration file
- show Show configuration files & locations
- state Get, set, or clear stored state
+<b><span class=g>Commands:</span></b>
+ <b><span class=c>shell</span></b> Shell integration setup
+ <b><span class=c>create</span></b> Create configuration file
+ <b><span class=c>show</span></b> Show configuration files &amp; locations
+ <b><span class=c>state</span></b> Get, set, or clear stored state
-Options:
- -h, --help
- Print help (see a summary with '-h')
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
## wt config create
@@ -342,7 +342,7 @@ approved-commands = ["npm install"]
# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),
# use a separate PROJECT config file at <repo>/.config/wt.toml
-# Run `wt config create --project` to create one, or see https://worktrunk.dev/hooks/
+# Run `wt config create --project` to create one, or see https://worktrunk.dev/hook/
# ============================================================================
# Custom Prompt Templates (Advanced)
@@ -589,28 +589,28 @@ With `--project`, creates `.config/wt.toml` in the current repository:
### Command reference
-```
+{% terminal() %}
wt config create - Create configuration file
-Usage: wt config create [OPTIONS]
+Usage: <b><span class=c>wt config create</span></b> <span class=c>[OPTIONS]</span>
-Options:
- --project
- Create project config (.config/wt.toml) instead of user config
+<b><span class=g>Options:</span></b>
+ <b><span class=c>--project</span></b>
+ Create project config (<b>.config/wt.toml</b>) instead of user config
- -h, --help
- Print help (see a summary with '-h')
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
## wt config state
@@ -660,34 +660,34 @@ wt config state clear
### Command reference
-```
+{% terminal() %}
wt config state - Get, set, or clear stored state
-Usage: wt config state [OPTIONS] <COMMAND>
+Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
-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
+<b><span class=g>Commands:</span></b>
+ <b><span class=c>default-branch</span></b> Default branch setting
+ <b><span class=c>previous-branch</span></b> Previous branch (for <b>wt switch -</b>)
+ <b><span class=c>ci-status</span></b> CI status cache
+ <b><span class=c>marker</span></b> Branch markers
+ <b><span class=c>logs</span></b> Background operation logs
+ <b><span class=c>get</span></b> Get all stored state
+ <b><span class=c>clear</span></b> Clear all stored state
-Options:
- -h, --help
- Print help (see a summary with '-h')
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
## wt config state default-branch
@@ -720,30 +720,30 @@ Without a subcommand, runs `get`. For `--refresh`, use `get --refresh`.
### Command reference
-```
+{% terminal() %}
wt config state default-branch - Default branch setting
-Usage: wt config state default-branch [OPTIONS] [COMMAND]
+Usage: <b><span class=c>wt config state default-branch</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>
-Commands:
- get Get the default branch
- set Set the default branch
- clear Clear the default branch cache
+<b><span class=g>Commands:</span></b>
+ <b><span class=c>get</span></b> Get the default branch
+ <b><span class=c>set</span></b> Set the default branch
+ <b><span class=c>clear</span></b> Clear the default branch cache
-Options:
- -h, --help
- Print help (see a summary with '-h')
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
## wt config state ci-status
@@ -779,29 +779,29 @@ Without a subcommand, runs `get` for the current branch. For `--branch` or `--re
### Command reference
-```
+{% terminal() %}
wt config state ci-status - CI status cache
-Usage: wt config state ci-status [OPTIONS] [COMMAND]
+Usage: <b><span class=c>wt config state ci-status</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>
-Commands:
- get Get CI status for a branch
- clear Clear CI status cache
+<b><span class=g>Commands:</span></b>
+ <b><span class=c>get</span></b> Get CI status for a branch
+ <b><span class=c>clear</span></b> Clear CI status cache
-Options:
- -h, --help
- Print help (see a summary with '-h')
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
## wt config state marker
@@ -837,30 +837,30 @@ Without a subcommand, runs `get` for the current branch. For `--branch`, use `ge
### Command reference
-```
+{% terminal() %}
wt config state marker - Branch markers
-Usage: wt config state marker [OPTIONS] [COMMAND]
+Usage: <b><span class=c>wt config state marker</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>
-Commands:
- get Get marker for a branch
- set Set marker for a branch
- clear Clear marker for a branch
+<b><span class=g>Commands:</span></b>
+ <b><span class=c>get</span></b> Get marker for a branch
+ <b><span class=c>set</span></b> Set marker for a branch
+ <b><span class=c>clear</span></b> Clear marker for a branch
-Options:
- -h, --help
- Print help (see a summary with '-h')
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
## wt config state logs
@@ -905,28 +905,28 @@ wt config state logs clear
### Command reference
-```
+{% terminal() %}
wt config state logs - Background operation logs
-Usage: wt config state logs [OPTIONS] [COMMAND]
+Usage: <b><span class=c>wt config state logs</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>
-Commands:
- get List background operation log files
- clear Clear background operation logs
+<b><span class=g>Commands:</span></b>
+ <b><span class=c>get</span></b> List background operation log files
+ <b><span class=c>clear</span></b> Clear background operation logs
-Options:
- -h, --help
- Print help (see a summary with '-h')
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
<!-- END AUTO-GENERATED from `wt config --help-page` -->
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 79db8ff05..eaa2f6f26 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -368,35 +368,35 @@ env = "cp {{ repo_root }}/.env.local .env"
## Command reference
-```
+{% terminal() %}
wt hook - Run hooks independently
-Usage: wt hook [OPTIONS] <COMMAND>
+Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
-Commands:
- show Show configured hooks
- post-create Run post-create hooks
- post-start Run post-start hooks
- pre-commit Run pre-commit hooks
- pre-merge Run pre-merge hooks
- post-merge Run post-merge hooks
- pre-remove Run pre-remove hooks
- approvals Manage command approvals
+<b><span class=g>Commands:</span></b>
+ <b><span class=c>show</span></b> Show configured hooks
+ <b><span class=c>post-create</span></b> Run post-create hooks
+ <b><span class=c>post-start</span></b> Run post-start hooks
+ <b><span class=c>pre-commit</span></b> Run pre-commit hooks
+ <b><span class=c>pre-merge</span></b> Run pre-merge hooks
+ <b><span class=c>post-merge</span></b> Run post-merge hooks
+ <b><span class=c>pre-remove</span></b> Run pre-remove hooks
+ <b><span class=c>approvals</span></b> Manage command approvals
-Options:
- -h, --help
- Print help (see a summary with '-h')
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
## wt hook approvals
@@ -438,28 +438,28 @@ wt hook approvals clear --global
### Command reference
-```
+{% terminal() %}
wt hook approvals - Manage command approvals
-Usage: wt hook approvals [OPTIONS] <COMMAND>
+Usage: <b><span class=c>wt hook approvals</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
-Commands:
- add Store approvals in config
- clear Clear approved commands from config
+<b><span class=g>Commands:</span></b>
+ <b><span class=c>add</span></b> Store approvals in config
+ <b><span class=c>clear</span></b> Clear approved commands from config
-Options:
- -h, --help
- Print help (see a summary with '-h')
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
<!-- END AUTO-GENERATED from `wt hook --help-page` -->
diff --git a/docs/content/list.md b/docs/content/list.md
index 649498c8b..c993eba9e 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -249,48 +249,48 @@ When `main_state == "integrated"`: `"ancestor"` `"trees_match"` `"no_added_chang
## Command reference
-```
+{% terminal() %}
wt list - List worktrees and optionally branches
-Usage: wt list [OPTIONS]
- wt list <COMMAND>
+Usage: <b><span class=c>wt list</span></b> <span class=c>[OPTIONS]</span>
+ <b><span class=c>wt list</span></b> <span class=c>&lt;COMMAND&gt;</span>
-Commands:
- statusline Single-line status for shell prompts
+<b><span class=g>Commands:</span></b>
+ <b><span class=c>statusline</span></b> Single-line status for shell prompts
-Options:
- --format <FORMAT>
+<b><span class=g>Options:</span></b>
+ <b><span class=c>--format</span></b><span class=c> &lt;FORMAT&gt;</span>
Output format (table, json)
[default: table]
- --branches
+ <b><span class=c>--branches</span></b>
Include branches without worktrees
- --remotes
+ <b><span class=c>--remotes</span></b>
Include remote branches
- --full
- Show CI and main diffstat
+ <b><span class=c>--full</span></b>
+ Show CI and <b>main</b> diffstat
- --progressive
+ <b><span class=c>--progressive</span></b>
Show fast info immediately, update with slow info
Displays local data (branches, paths, status) first, then updates with
remote data (CI, upstream) as it arrives. Auto-enabled for TTY.
- -h, --help
- Print help (see a summary with '-h')
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
<!-- END AUTO-GENERATED from `wt list --help-page` -->
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 9ca4ebe84..cdde28c6c 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -83,60 +83,60 @@ lint = "cargo clippy"
## Command reference
-```
+{% terminal() %}
wt merge - Merge worktree into target branch
Squashes commits, rebases, runs hooks, merges to target, and removes the
worktree.
-Usage: wt merge [OPTIONS] [TARGET]
+Usage: <b><span class=c>wt merge</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>
-Arguments:
- [TARGET]
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[TARGET]</span>
Target branch
Defaults to default branch.
-Options:
- --no-squash
+<b><span class=g>Options:</span></b>
+ <b><span class=c>--no-squash</span></b>
Skip commit squashing
- --no-commit
+ <b><span class=c>--no-commit</span></b>
Skip commit and squash
- --no-rebase
+ <b><span class=c>--no-rebase</span></b>
Skip rebase (fail if not already rebased)
- --no-remove
+ <b><span class=c>--no-remove</span></b>
Keep worktree after merge
- --no-verify
+ <b><span class=c>--no-verify</span></b>
Skip hooks
- -f, --force
+ <b><span class=c>-f</span></b>, <b><span class=c>--force</span></b>
Skip approval prompts
- --stage <STAGE>
+ <b><span class=c>--stage</span></b><span class=c> &lt;STAGE&gt;</span>
What to stage before committing [default: all]
Possible values:
- - all: Stage everything: untracked files + unstaged tracked
+ - <b><span class=c>all</span></b>: Stage everything: untracked files + unstaged tracked
changes
- - tracked: Stage tracked changes only (like git add -u)
- - none: Stage nothing, commit only what's already in the index
+ - <b><span class=c>tracked</span></b>: Stage tracked changes only (like <b>git add -u</b>)
+ - <b><span class=c>none</span></b>: Stage nothing, commit only what&#39;s already in the index
- -h, --help
- Print help (see a summary with '-h')
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
<!-- END AUTO-GENERATED from `wt merge --help-page` -->
diff --git a/docs/content/remove.md b/docs/content/remove.md
index 3002a8dfa..b002041a9 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -70,43 +70,43 @@ Removal runs in the background by default (returns immediately). Logs are writte
## Command reference
-```
+{% terminal() %}
wt remove - Remove worktree and branch
-Usage: wt remove [OPTIONS] [WORKTREES]...
+Usage: <b><span class=c>wt remove</span></b> <span class=c>[OPTIONS]</span> <span class=c>[WORKTREES]...</span>
-Arguments:
- [WORKTREES]...
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[WORKTREES]...</span>
Worktree or branch (@ for current)
-Options:
- --no-delete-branch
+<b><span class=g>Options:</span></b>
+ <b><span class=c>--no-delete-branch</span></b>
Keep branch after removal
- -D, --force-delete
+ <b><span class=c>-D</span></b>, <b><span class=c>--force-delete</span></b>
Delete unmerged branches
- --no-background
+ <b><span class=c>--no-background</span></b>
Run removal in foreground
- --no-verify
+ <b><span class=c>--no-verify</span></b>
Skip hooks
- --force
+ <b><span class=c>--force</span></b>
Skip approval prompts
- -h, --help
- Print help (see a summary with '-h')
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
<!-- END AUTO-GENERATED from `wt remove --help-page` -->
diff --git a/docs/content/select.md b/docs/content/select.md
index 7fa7bf7ae..4f4a3f6d6 100644
--- a/docs/content/select.md
+++ b/docs/content/select.md
@@ -54,26 +54,26 @@ Branches without worktrees are included — selecting one creates a worktree. (`
## Command reference
-```
+{% terminal() %}
wt select - Interactive worktree selector
Toggle preview tabs with 1/2/3 keys. Toggle preview visibility with alt-p.
-Usage: wt select [OPTIONS]
+Usage: <b><span class=c>wt select</span></b> <span class=c>[OPTIONS]</span>
-Options:
- -h, --help
- Print help (see a summary with '-h')
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
<!-- END AUTO-GENERATED from `wt select --help-page` -->
diff --git a/docs/content/step.md b/docs/content/step.md
index 19aa4c62f..0d21035c7 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -43,32 +43,32 @@ wt step push
## Command reference
-```
+{% terminal() %}
wt step - Run individual workflow operations
-Usage: wt step [OPTIONS] <COMMAND>
+Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
-Commands:
- commit Commit changes with LLM commit message
- squash Squash commits down to target
- push Push changes to local target branch
- rebase Rebase onto target
- for-each [experimental] Run command in each worktree
+<b><span class=g>Commands:</span></b>
+ <b><span class=c>commit</span></b> Commit changes with LLM commit message
+ <b><span class=c>squash</span></b> Squash commits down to target
+ <b><span class=c>push</span></b> Push changes to local target branch
+ <b><span class=c>rebase</span></b> Rebase onto target
+ <b><span class=c>for-each</span></b> [experimental] Run command in each worktree
-Options:
- -h, --help
- Print help (see a summary with '-h')
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
## wt step for-each
@@ -125,28 +125,28 @@ Note: This command is experimental and may change in future versions.
### Command reference
-```
+{% terminal() %}
wt step for-each - [experimental] Run command in each worktree
-Usage: wt step for-each [OPTIONS] -- <ARGS>...
+Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</span> <b><span class=c>--</span></b> <span class=c>&lt;ARGS&gt;...</span>
-Arguments:
- <ARGS>...
+<b><span class=g>Arguments:</span></b>
+ <span class=c>&lt;ARGS&gt;...</span>
Command template (see --help for all variables)
-Options:
- -h, --help
- Print help (see a summary with '-h')
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
<!-- END AUTO-GENERATED from `wt step --help-page` -->
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 2092bc006..4c5e3b3da 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -64,33 +64,33 @@ wt switch --create fix --base=@ # Branch from current HEAD
## Command reference
-```
+{% terminal() %}
wt switch - Switch to a worktree
-Usage: wt switch [OPTIONS] <BRANCH> [-- <EXECUTE_ARGS>...]
+Usage: <b><span class=c>wt switch</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;BRANCH&gt;</span> <b><span class=c>[--</span></b> <span class=c>&lt;EXECUTE_ARGS&gt;...</span><b><span class=c>]</span></b>
-Arguments:
- <BRANCH>
+<b><span class=g>Arguments:</span></b>
+ <span class=c>&lt;BRANCH&gt;</span>
Branch or worktree name
- Shortcuts: '^' (main), '-' (previous), '@' (current)
+ Shortcuts: &#39;^&#39; (main), &#39;-&#39; (previous), &#39;@&#39; (current)
- [EXECUTE_ARGS]...
+ <span class=c>[EXECUTE_ARGS]...</span>
Additional arguments for --execute command (after --)
- Arguments after -- are appended to the execute command. Each argument
+ Arguments after <b>--</b> are appended to the execute command. Each argument
is POSIX shell-escaped before appending.
-Options:
- -c, --create
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-c</span></b>, <b><span class=c>--create</span></b>
Create a new branch
- -b, --base <BASE>
+ <b><span class=c>-b</span></b>, <b><span class=c>--base</span></b><span class=c> &lt;BASE&gt;</span>
Base branch
Defaults to default branch.
- -x, --execute <EXECUTE>
+ <b><span class=c>-x</span></b>, <b><span class=c>--execute</span></b><span class=c> &lt;EXECUTE&gt;</span>
Command to run after switch
Replaces the wt process with the command after switching, giving it
@@ -99,34 +99,34 @@ Options:
Especially useful with shell aliases:
- alias wsc='wt switch --create -x claude'
- wsc feature-branch -- 'implement the login flow'
+ <b>alias wsc=&#39;wt switch --create -x claude&#39;</b>
+ <b>wsc feature-branch -- &#39;implement the login flow&#39;</b>
- Then wsc feature-branch creates the worktree and launches Claude Code.
- Arguments after -- are passed to the command, so wsc feature --
- 'implement login' works.
+ Then <b>wsc feature-branch</b> creates the worktree and launches Claude Code.
+ Arguments after <b>--</b> are passed to the command, so <b>wsc feature --</b>
+ &#39;implement login&#39; works.
- -f, --force
+ <b><span class=c>-f</span></b>, <b><span class=c>--force</span></b>
Skip approval prompts
- --clobber
+ <b><span class=c>--clobber</span></b>
Remove stale paths at target
- --no-verify
+ <b><span class=c>--no-verify</span></b>
Skip hooks
- -h, --help
- Print help (see a summary with '-h')
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
-Global Options:
- -C <path>
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
Working directory for this command
- --config <path>
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
User config file path
- -v, --verbose
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b>
Show commands and debug info
-```
+{% end %}
<!-- END AUTO-GENERATED from `wt switch --help-page` -->
diff --git a/src/commands/config.rs b/src/commands/config.rs
index 619d2b2f0..28e847931 100644
--- a/src/commands/config.rs
+++ b/src/commands/config.rs
@@ -61,7 +61,7 @@ pub fn handle_config_create(project: bool) -> anyhow::Result<()> {
"Project config",
&[
"Edit this file to configure hooks for this repository",
- "See https://worktrunk.dev/hooks/ for hook documentation",
+ "See https://worktrunk.dev/hook/ for hook documentation",
],
)
} else {
diff --git a/src/main.rs b/src/main.rs
index 6fd95f25d..f92be0078 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -161,7 +161,8 @@ fn maybe_handle_help_with_pager() -> bool {
///
/// Returns the usage/options/subcommands section without the after_long_help content.
/// If `width` is provided, wraps text at that width (for web docs); otherwise uses default.
-fn get_help_reference(command_path: &[&str], width: Option<usize>) -> String {
+/// If `with_colors` is true, preserves ANSI color codes for HTML conversion.
+fn get_help_reference(command_path: &[&str], width: Option<usize>, with_colors: bool) -> String {
use clap::ColorChoice;
use clap::error::ErrorKind;
@@ -171,7 +172,11 @@ fn get_help_reference(command_path: &[&str], width: Option<usize>) -> String {
args.push("--help".to_string());
let mut cmd = cli::build_command();
- cmd = cmd.color(ColorChoice::Never);
+ cmd = cmd.color(if with_colors {
+ ColorChoice::Always
+ } else {
+ ColorChoice::Never
+ });
if let Some(w) = width {
cmd = cmd.term_width(w);
}
@@ -181,9 +186,14 @@ fn get_help_reference(command_path: &[&str], width: Option<usize>) -> String {
err.kind(),
ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
) {
- err.render()
- .to_string()
- .replace("```text\n", "```\n")
+ let rendered = err.render();
+ // .ansi() returns ANSI-styled output, .to_string() strips colors
+ let text = if with_colors {
+ rendered.ansi().to_string()
+ } else {
+ rendered.to_string()
+ };
+ text.replace("```text\n", "```\n")
.replace("```console\n", "```bash\n")
} else {
return String::new();
@@ -210,20 +220,23 @@ fn find_after_help_start(help: &str) -> Option<usize> {
let mut offset = 0;
for line in help.lines() {
- if line.starts_with("Global Options:") {
+ // Strip ANSI codes for pattern matching
+ let plain_line = strip_ansi_codes(line);
+
+ if plain_line.starts_with("Global Options:") {
past_global_options = true;
offset += line.len() + 1;
continue;
}
if past_global_options {
- if line.is_empty() {
+ if plain_line.is_empty() {
saw_blank_after_options = true;
blank_offset = Some(offset);
- } else if saw_blank_after_options && !line.starts_with(' ') {
+ } else if saw_blank_after_options && !plain_line.starts_with(' ') {
// Non-indented line after blank = start of after_long_help
return blank_offset;
- } else if line.starts_with(' ') {
+ } else if plain_line.starts_with(' ') {
// Still in indented options, reset blank tracking
saw_blank_after_options = false;
}
@@ -233,6 +246,31 @@ fn find_after_help_start(help: &str) -> Option<usize> {
None
}
+/// Strip ANSI escape codes from a string for pattern matching.
+fn strip_ansi_codes(s: &str) -> String {
+ let mut result = String::with_capacity(s.len());
+ let mut chars = s.chars().peekable();
+
+ while let Some(c) = chars.next() {
+ if c == '\x1b' {
+ // Skip escape sequence: ESC [ ... m (SGR) or ESC [ ... other
+ if chars.peek() == Some(&'[') {
+ chars.next(); // consume '['
+ // Consume until we hit a letter (the command character)
+ while let Some(&next) = chars.peek() {
+ chars.next();
+ if next.is_ascii_alphabetic() {
+ break;
+ }
+ }
+ }
+ } else {
+ result.push(c);
+ }
+ }
+ result
+}
+
/// Generate a full documentation page for a command.
///
/// Output format:
@@ -307,37 +345,38 @@ fn handle_help_page(args: &[String]) {
colorize_ci_status_for_html(&text)
};
- // Get the help reference block (wrap at 80 chars for web docs)
- let reference_block = get_help_reference(&[subcommand], Some(80));
+ // Get the help reference block (wrap at 80 chars for web docs, with colors for HTML)
+ let reference_block = get_help_reference(&[subcommand], Some(80), true);
// Output the generated content (frontmatter is in skeleton files)
// Uses region markers so sync can replace just this content
// END tag mirrors the ID for unambiguous matching with nested markers
- println!(
+ // Use std::println! to preserve ANSI codes in output (the styling::println strips them)
+ std::println!(
"<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->"
);
- println!();
- println!("{}", main_help.trim());
- println!();
+ std::println!();
+ std::println!("{}", main_help.trim());
+ std::println!();
// Main command reference immediately after its content
- println!("## Command reference");
- println!();
- println!("```");
- print!("{}", reference_block.trim());
- println!();
- println!("```");
+ std::println!("## Command reference");
+ std::println!();
+ std::println!("```");
+ std::print!("{}", reference_block.trim());
+ std::println!();
+ std::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());
+ std::println!();
+ std::println!("{}", subdocs_processed.trim());
}
- println!();
- println!("<!-- END AUTO-GENERATED from `wt {subcommand} --help-page` -->");
+ std::println!();
+ std::println!("<!-- END AUTO-GENERATED from `wt {subcommand} --help-page` -->");
}
/// Add HTML color spans for CI status dots in help page output.
@@ -475,8 +514,8 @@ fn format_subcommand_section(
.chain(std::iter::once(subcommand_name))
.collect();
- // Get help reference (wrap at 80 chars for web docs)
- let reference_block = get_help_reference(&command_path, Some(80));
+ // Get help reference (wrap at 80 chars for web docs, with colors for HTML)
+ let reference_block = get_help_reference(&command_path, Some(80), true);
// Format the section: heading, main content, command reference, then nested subdocs
let mut section = format!("## {}\n\n", full_command);
diff --git a/tests/integration_tests/config_init.rs b/tests/integration_tests/config_init.rs
index e63bb503e..d7ff314c6 100644
--- a/tests/integration_tests/config_init.rs
+++ b/tests/integration_tests/config_init.rs
@@ -84,7 +84,7 @@ fn test_config_create_project_creates_file(repo: TestRepo) {
✓ Created project config: _REPO_/.config/wt.toml
↳ Edit this file to configure hooks for this repository
- ↳ See https://worktrunk.dev/hooks/ for hook documentation
+ ↳ See https://worktrunk.dev/hook/ for hook documentation
");
});
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index f586575f4..780802a0e 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -485,6 +485,47 @@ fn clean_ansi_html(html: &str) -> String {
.replace("<span style='color:var(--cyan,#0aa)'>", "<span class=c>")
}
+/// Regex to find command reference code blocks with ANSI content
+/// Matches: ## Command reference\n\n```\n<content with ANSI>\n```
+/// or: ### Command reference\n\n```\n<content with ANSI>\n```
+static COMMAND_REF_BLOCK_PATTERN: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r"(?s)(###? Command reference\n\n)```\n(.*?)\n```").unwrap());
+
+/// Convert command reference code blocks to terminal shortcodes with HTML
+///
+/// Finds code blocks after "## Command reference" or "### Command reference" headers
+/// and converts ANSI escape codes to HTML, wrapping in {% terminal() %} shortcode.
+fn convert_command_reference_to_html(content: &str) -> Result<String, String> {
+ let mut result = content.to_string();
+
+ // Find all command reference blocks and convert them
+ // Process in reverse order to preserve positions
+ let matches: Vec<_> = COMMAND_REF_BLOCK_PATTERN
+ .captures_iter(content)
+ .map(|cap| {
+ let full_match = cap.get(0).unwrap();
+ let header = cap.get(1).unwrap().as_str();
+ let code_content = cap.get(2).unwrap().as_str();
+ (full_match.start(), full_match.end(), header, code_content)
+ })
+ .collect();
+
+ for (start, end, header, code_content) in matches.into_iter().rev() {
+ // Convert ANSI to HTML
+ let with_resets = ensure_line_resets(code_content);
+ let html =
+ ansi_to_html(&with_resets).map_err(|e| format!("ANSI conversion failed: {e}"))?;
+ let clean_html = clean_ansi_html(&html);
+ let trimmed_html = trim_lines(&clean_html);
+
+ // Build terminal shortcode
+ let replacement = format!("{header}{{% terminal() %}}\n{trimmed_html}\n{{% end %}}");
+ result.replace_range(start..end, &replacement);
+ }
+
+ Ok(result)
+}
+
/// Get help output for a command
///
/// Expected format: `wt <subcommand> --help-md` (ID includes backticks from marker)
@@ -1151,6 +1192,18 @@ fn test_command_pages_are_in_sync() {
}
};
+ // Convert command reference code blocks to terminal shortcodes with HTML
+ let generated = match convert_command_reference_to_html(&generated) {
+ Ok(converted) => converted,
+ Err(e) => {
+ errors.push(format!(
+ "Failed to convert command reference for '{}': {}",
+ cmd, e
+ ));
+ continue;
+ }
+ };
+
let current = fs::read_to_string(&doc_path)
.unwrap_or_else(|e| panic!("Failed to read {}: {}", doc_path.display(), e));
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index b39160a46..551e83011 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -117,7 +117,7 @@ Creates ~/.config/worktrunk/config.toml with the following content:

# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),
# use a separate PROJECT config file at <repo>/.config/wt.toml
- # Run `wt config create --project` to create one, or see https://worktrunk.dev/hooks/
+ # Run `wt config create --project` to create one, or see https://worktrunk.dev/hook/

# ============================================================================
# Custom Prompt Templates (Advanced)
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_merge.snap b/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
index 858dd8e49..3161e992b 100644
--- a/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
@@ -94,58 +94,58 @@ lint = "cargo clippy"
## Command reference
```
-wt merge - Merge worktree into target branch
-
+wt merge - Merge worktree into target branch
+
Squashes commits, rebases, runs hooks, merges to target, and removes the
-worktree.
+worktree.
-Usage: wt merge [OPTIONS] [TARGET]
+Usage: wt merge [OPTIONS] [TARGET]
-Arguments:
- [TARGET]
- Target branch
-
- Defaults to default branch.
+Arguments:
+ [TARGET]
+ Target branch
+ 
+ Defaults to default branch.
-Options:
- --no-squash
+Options:
+ --no-squash
Skip commit squashing
- --no-commit
+ --no-commit
Skip commit and squash
- --no-rebase
+ --no-rebase
Skip rebase (fail if not already rebased)
- --no-remove
+ --no-remove
Keep worktree after merge
- --no-verify
+ --no-verify
Skip hooks
- -f, --force
+ -f, --force
Skip approval prompts
- --stage <STAGE>
+ --stage <STAGE>
What to stage before committing [default: all]
Possible values:
- - all: Stage everything: untracked files + unstaged tracked
+ - all: Stage everything: untracked files + unstaged tracked
changes
- - tracked: Stage tracked changes only (like git add -u)
- - none: Stage nothing, commit only what's already in the index
+ - tracked: Stage tracked changes only (like git add -u)
+ - none: Stage nothing, commit only what's already in the index
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose
+ -v, --verbose
Show commands and debug info
```
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
index e666ca42b..3c3890c39 100644
--- a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
@@ -77,65 +77,65 @@ wt switch --create fix --base=@ # Branch from current HEAD
```
wt switch - Switch to a worktree
-Usage: wt switch [OPTIONS] <BRANCH> [-- <EXECUTE_ARGS>...]
-
-Arguments:
- <BRANCH>
- Branch or worktree name
-
- Shortcuts: '^' (main), '-' (previous), '@' (current)
-
- [EXECUTE_ARGS]...
- Additional arguments for --execute command (after --)
-
- Arguments after -- are appended to the execute command. Each argument
- is POSIX shell-escaped before appending.
-
-Options:
- -c, --create
+Usage: wt switch [OPTIONS] <BRANCH> [-- <EXECUTE_ARGS>...]
+
+Arguments:
+ <BRANCH>
+ Branch or worktree name
+ 
+ Shortcuts: '^' (main), '-' (previous), '@' (current)
+
+ [EXECUTE_ARGS]...
+ Additional arguments for --execute command (after --)
+ 
+ Arguments after -- are appended to the execute command. Each argument
+ is POSIX shell-escaped before appending.
+
+Options:
+ -c, --create
Create a new branch
- -b, --base <BASE>
- Base branch
-
- Defaults to default branch.
+ -b, --base <BASE>
+ Base branch
+ 
+ Defaults to default branch.
- -x, --execute <EXECUTE>
- Command to run after switch
-
+ -x, --execute <EXECUTE>
+ Command to run after switch
+ 
Replaces the wt process with the command after switching, giving it
full terminal control. Useful for launching editors, AI agents, or
- other interactive tools.
-
- Especially useful with shell aliases:
-
- alias wsc='wt switch --create -x claude'
- wsc feature-branch -- 'implement the login flow'
-
- Then wsc feature-branch creates the worktree and launches Claude Code.
- Arguments after -- are passed to the command, so wsc feature --
- 'implement login' works.
-
- -f, --force
+ other interactive tools.
+ 
+ Especially useful with shell aliases:
+ 
+ alias wsc='wt switch --create -x claude'
+ wsc feature-branch -- 'implement the login flow'
+ 
+ Then wsc feature-branch creates the worktree and launches Claude Code.
+ Arguments after -- are passed to the command, so wsc feature --
+ 'implement login' works.
+
+ -f, --force
Skip approval prompts
- --clobber
+ --clobber
Remove stale paths at target
- --no-verify
+ --no-verify
Skip hooks
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose
+ -v, --verbose
Show commands and debug info
```