Skip to content

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

Consistent code block convention for syntax highlighting (#1777)

Maximilian Roosb6a674438090
diff --git a/README.md b/README.md
index 22c1d816e..345c3f411 100644
--- a/README.md
+++ b/README.md
@@ -104,27 +104,20 @@ A demo with some advanced features:
**Homebrew (macOS & Linux):**
-```bash
-brew install worktrunk && wt config shell install
-```
+{{ terminal(cmd="brew install worktrunk && wt config shell install") }}
Shell integration allows commands to change directories.
**Cargo:**
-```bash
-cargo install worktrunk && wt config shell install
-```
+{{ terminal(cmd="cargo install worktrunk && wt config shell install") }}
<details>
<summary><strong>Windows</strong></summary>
On Windows, `wt` defaults to Windows Terminal's command. Winget additionally installs Worktrunk as `git-wt` to avoid the conflict:
-```bash
-winget install max-sixty.worktrunk
-git-wt config shell install
-```
+{{ terminal(cmd="winget install max-sixty.worktrunk|||git-wt config shell install") }}
Alternatively, disable Windows Terminal's alias (Settings → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal") to use `wt` directly.
@@ -132,9 +125,7 @@ Alternatively, disable Windows Terminal's alias (Settings → Privacy & security
**Arch Linux:**
-```bash
-paru worktrunk-bin && wt config shell install
-```
+{{ terminal(cmd="paru worktrunk-bin && wt config shell install") }}
## Quick start
@@ -164,11 +155,7 @@ When done, either:
**PR workflow** — commit, push, open a PR, merge via GitHub/GitLab, then clean up:
-```bash
-wt step commit # commit staged changes
-gh pr create # or glab mr create
-wt remove # after PR is merged
-```
+{{ terminal(cmd="wt step commit # commit staged changes|||gh pr create # or glab mr create|||wt remove # after PR is merged") }}
**Local merge** — squash, rebase onto main, fast-forward merge, clean up:
@@ -190,11 +177,7 @@ $ wt merge main
For parallel agents, create multiple worktrees and launch an agent in each:
-```bash
-wt switch -x claude -c feature-a -- 'Add user authentication'
-wt switch -x claude -c feature-b -- 'Fix the pagination bug'
-wt switch -x claude -c feature-c -- 'Write tests for the API'
-```
+{{ terminal(cmd="wt switch -x claude -c feature-a -- 'Add user authentication'|||wt switch -x claude -c feature-b -- 'Fix the pagination bug'|||wt switch -x claude -c feature-c -- 'Write tests for the API'") }}
The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](https://worktrunk.dev/hook/) to automate setup (install deps, start dev servers).
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index f6d8ac4d2..e45717b03 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -181,15 +181,15 @@ Each command has three documentation pieces in `src/cli.rs`:
The `wt list` examples use **HTML comments + code blocks** that expand to full snapshot output. In `cli.rs`, you write:
-```
+`````
<!-- wt list -->
```console
-$ wt list
-```
+wt list
```
+`````
This renders differently in each context:
-- **Terminal help (`--help`)**: HTML comment skipped, code block shows as dimmed `$ wt list`
+- **Terminal help (`--help`)**: HTML comment skipped, code block shows as dimmed `wt list`
- **Web docs (`--help-page`)**: Both are replaced with the standard template format:
```
@@ -220,6 +220,20 @@ This renders differently in each context:
The examples in `cli.rs` are just command stubs — the actual output comes from snapshots generated by integration tests. This ensures docs always match real CLI behavior.
+### Code block convention
+
+All shell commands use `$ ` prefix in `` ```console `` blocks. `convert_dollar_console_to_terminal()` (`src/docs.rs`, shared library function) converts them to terminal shortcodes. The sync test also runs this on hand-written docs.
+
+| Detected pattern | Web output | Highlighting |
+|------------------|------------|--------------|
+| Any `$ ` commands, no `{{ }}` | `cmd` parameter with `\|\|\|` delimiter | Full Syntect |
+| `{{ }}` in command | `{% terminal() %}` with `<span class="cmd">` body | Accent color only |
+| No `$ ` | `console` → `bash` conversion | Syntect (no `$ ` prompt) |
+
+The `cmd` parameter supports multiple commands joined by `|||`. The template splits, highlights each through Syntect individually, and wraps commands in `<span class="cmd">` (CSS `::before` adds `$ `). Comment lines (`#`) are highlighted but not wrapped (no prompt).
+
+Hand-written docs can use either `console` fences with `$ ` (auto-converted by the sync test) or shortcodes directly.
+
### CLI and web compatibility
Content in `after_long_help` must work in **both** the terminal (`--help`) and the web docs:
@@ -235,7 +249,8 @@ The `--help-page` generator in `src/main.rs` applies post-processing to transfor
| CLI Source | Web Output |
|------------|------------|
-| `` ```console `` | `` ```bash `` |
+| `` ```console `` with `$ ` | `{% terminal() %}` with `<span class="cmd">` |
+| `` ```console `` (no `$ `) | `` ```bash `` |
| `` `●` green `` | `<span style='color:#0a0'>●</span> green` |
| `` `●` blue `` | `<span style='color:#00a'>●</span> blue` |
| `` `●` red `` | `<span style='color:#a00'>●</span> red` |
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.md
index 7ebac2528..d8b444e9f 100644
--- a/docs/content/claude-code.md
+++ b/docs/content/claude-code.md
@@ -14,10 +14,10 @@ The worktrunk Claude Code plugin provides two features:
## Installation
-```bash
-$ claude plugin marketplace add max-sixty/worktrunk
-$ claude plugin install worktrunk@worktrunk
-```
+{% terminal() %}
+<span class="cmd">claude plugin marketplace add max-sixty/worktrunk</span>
+<span class="cmd">claude plugin install worktrunk@worktrunk</span>
+{% end %}
## Configuration skill
@@ -56,11 +56,11 @@ The plugin tracks Claude sessions with status markers in `wt list`:
Set status markers manually for any workflow:
-```bash
-$ wt config state marker set "🚧" # Current branch
-$ wt config state marker set "✅" --branch feature # Specific branch
-$ git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct
-```
+{% terminal() %}
+<span class="cmd">wt config state marker set "🚧" # Current branch</span>
+<span class="cmd">wt config state marker set "✅" --branch feature # Specific branch</span>
+<span class="cmd">git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct</span>
+{% end %}
## Statusline
diff --git a/docs/content/config.md b/docs/content/config.md
index dafabcede..d6d88d0b8 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -15,27 +15,19 @@ Manage user & project configs. Includes shell integration, hooks, and saved stat
Install shell integration (required for directory switching):
-```bash
-wt config shell install
-```
+{{ terminal(cmd="wt config shell install") }}
Create user config file with documented examples:
-```bash
-wt config create
-```
+{{ terminal(cmd="wt config create") }}
Create project config file (`.config/wt.toml`) for hooks:
-```bash
-wt config create --project
-```
+{{ terminal(cmd="wt config create --project") }}
Show current configuration and file locations:
-```bash
-wt config show
-```
+{{ terminal(cmd="wt config show") }}
## Configuration files
@@ -383,9 +375,7 @@ test = "cargo test"
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
-```bash
-wt config shell install
-```
+{{ terminal(cmd="wt config shell install") }}
For manual setup, see `wt config shell init --help`.
@@ -419,9 +409,7 @@ Note the single underscore after `WORKTRUNK` and double underscores between nest
Override the LLM command in CI to use a mock:
-```bash
-WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
-```
+{{ terminal(cmd="WORKTRUNK_COMMIT__GENERATION__COMMAND=&quot;echo 'test: automated commit'&quot; wt merge") }}
### Other environment variables
@@ -483,9 +471,7 @@ If a config file doesn't exist, shows defaults that would be used.
Use `--full` to run diagnostic checks:
-```bash
-wt config show --full
-```
+{{ terminal(cmd="wt config show --full") }}
This tests:
- **CI tool status** — Whether `gh` (GitHub) or `glab` (GitLab) is installed and authenticated
@@ -535,34 +521,22 @@ Use `wt config show` to view file-based configuration.
### Examples
Get the default branch:
-```bash
-wt config state default-branch
-```
+{{ terminal(cmd="wt config state default-branch") }}
Set the default branch manually:
-```bash
-wt config state default-branch set main
-```
+{{ terminal(cmd="wt config state default-branch set main") }}
Set a marker for current branch:
-```bash
-wt config state marker set "🚧 WIP"
-```
+{{ terminal(cmd="wt config state marker set &quot;🚧 WIP&quot;") }}
Clear all CI status cache:
-```bash
-wt config state ci-status clear --all
-```
+{{ terminal(cmd="wt config state ci-status clear --all") }}
Show all stored state:
-```bash
-wt config state get
-```
+{{ terminal(cmd="wt config state get") }}
Clear all stored state:
-```bash
-wt config state clear
-```
+{{ terminal(cmd="wt config state clear") }}
### Command reference
@@ -732,9 +706,7 @@ bugfix 🤖!↑⇡ ~/code/myproject.bugfix
Stored in git config as `worktrunk.state.<branch>.marker`. Set directly with:
-```bash
-git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
-```
+{{ terminal(cmd="git config worktrunk.state.feature.marker '{&quot;marker&quot;:&quot;🚧&quot;,&quot;set_at&quot;:0}'") }}
Without a subcommand, runs `get` for the current branch. For `--branch`, use `get --branch=NAME`.
@@ -801,24 +773,16 @@ All logs are stored in `.git/wt/logs/` (in the main worktree's git directory).
### Examples
List all log files:
-```bash
-wt config state logs get
-```
+{{ terminal(cmd="wt config state logs get") }}
Query the command log:
-```bash
-tail -5 .git/wt/logs/commands.jsonl | jq .
-```
+{{ terminal(cmd="tail -5 .git/wt/logs/commands.jsonl | jq .") }}
View a specific hook log:
-```bash
-cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"
-```
+{{ terminal(cmd="cat &quot;$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log&quot;") }}
Clear all logs:
-```bash
-wt config state logs clear
-```
+{{ terminal(cmd="wt config state logs clear") }}
### Command reference
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 48f26c584..8a3cf6ff2 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -17,24 +17,24 @@ Branch switching uses one directory: uncommitted changes from one agent get mixe
Git's built-in worktree commands work but require manual lifecycle management:
-```bash
+{% terminal() %}
# Plain git worktree workflow
-git worktree add -b feature-branch ../myapp-feature main
-cd ../myapp-feature
+<span class="cmd">git worktree add -b feature-branch ../myapp-feature main</span>
+<span class="cmd">cd ../myapp-feature</span>
# ...work, commit, push...
-cd ../myapp
-git merge feature-branch
-git worktree remove ../myapp-feature
-git branch -d feature-branch
-```
+<span class="cmd">cd ../myapp</span>
+<span class="cmd">git merge feature-branch</span>
+<span class="cmd">git worktree remove ../myapp-feature</span>
+<span class="cmd">git branch -d feature-branch</span>
+{% end %}
Worktrunk automates the full lifecycle:
-```bash
-wt switch --create feature-branch # Creates worktree, runs setup hooks
+{% terminal() %}
+<span class="cmd">wt switch --create feature-branch # Creates worktree, runs setup hooks</span>
# ...work...
-wt merge # Merges into default branch, cleans up
-```
+<span class="cmd">wt merge # Merges into default branch, cleans up</span>
+{% end %}
No cd back to main — `wt merge` runs from the feature worktree and merges into the target, like GitHub's merge button.
@@ -139,9 +139,7 @@ Worktrunk can delete **worktrees** and **branches**. Both have safeguards.
For worktrees containing precious ignored data (databases, caches, large assets), use `git worktree lock`:
-```bash
-git worktree lock ../myproject.feature --reason "Contains local database"
-```
+{{ terminal(cmd="git worktree lock ../myproject.feature --reason \"Contains local database\"") }}
Locked worktrees show `⊞` in `wt list`. Neither `git worktree remove` nor `wt remove` (even with `--force`) will delete them. Unlock with `git worktree unlock`.
@@ -194,13 +192,13 @@ All hook executions and LLM commands are recorded in `.git/wt/logs/commands.json
View the log with `wt config state logs get`, or query directly:
-```bash
+{% terminal() %}
# Recent commands
-tail -5 .git/wt/logs/commands.jsonl | jq .
+<span class="cmd">tail -5 .git/wt/logs/commands.jsonl | jq .</span>
# Failed commands
-jq 'select(.exit != 0 and .exit != null)' .git/wt/logs/commands.jsonl
-```
+<span class="cmd">jq 'select(.exit != 0 and .exit != null)' .git/wt/logs/commands.jsonl</span>
+{% end %}
Clear with `wt config state logs clear`.
@@ -224,9 +222,7 @@ For full details on the detection mechanism, see `wt config state default-branch
Errors related to tree-sitter or C compilation (C99 mode, `le16toh` undefined) can be avoided by installing without syntax highlighting:
-```bash
-$ cargo install worktrunk --no-default-features
-```
+{{ terminal(cmd="cargo install worktrunk --no-default-features") }}
This disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.
@@ -234,17 +230,13 @@ This disables bash syntax highlighting in command output but keeps all core func
### Quick tests
-```bash
-$ cargo test
-```
+{{ terminal(cmd="cargo test") }}
### Full integration tests
Shell integration tests require bash, zsh, fish, and nushell:
-```bash
-$ cargo test --test integration --features shell-integration-tests
-```
+{{ terminal(cmd="cargo test --test integration --features shell-integration-tests") }}
## How can I contribute?
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 70fcacc3e..165f46fbb 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -286,16 +286,7 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:
`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.
-```bash
-wt hook pre-merge # Run all pre-merge hooks
-wt hook pre-merge test # Run hooks named "test" from both sources
-wt hook pre-merge user: # Run all user hooks
-wt hook pre-merge project: # Run all project hooks
-wt hook pre-merge user:test # Run only user's "test" hook
-wt hook pre-merge project:test # Run only project's "test" hook
-wt hook pre-merge --yes # Skip approval prompts (for CI)
-wt hook pre-start --var branch=feature/test # Override template variable
-```
+{{ terminal(cmd="wt hook pre-merge # Run all pre-merge hooks|||wt hook pre-merge test # Run hooks named &quot;test&quot; from both sources|||wt hook pre-merge user: # Run all user hooks|||wt hook pre-merge project: # Run all project hooks|||wt hook pre-merge user:test # Run only user's &quot;test&quot; hook|||wt hook pre-merge project:test # Run only project's &quot;test&quot; hook|||wt hook pre-merge --yes # Skip approval prompts (for CI)|||wt hook pre-start --var branch=feature/test # Override template variable") }}
The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.
@@ -546,19 +537,13 @@ Project hooks require approval on first run to prevent untrusted projects from r
### Examples
Pre-approve all commands for current project:
-```bash
-wt hook approvals add
-```
+{{ terminal(cmd="wt hook approvals add") }}
Clear approvals for current project:
-```bash
-wt hook approvals clear
-```
+{{ terminal(cmd="wt hook approvals clear") }}
Clear global approvals:
-```bash
-wt hook approvals clear --global
-```
+{{ terminal(cmd="wt hook approvals clear --global") }}
### How approvals work
diff --git a/docs/content/list.md b/docs/content/list.md
index 66889f41d..06585a7f6 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -30,59 +30,22 @@ The table renders progressively: branch names, paths, and commit hashes appear i
List all worktrees:
-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_list.snap — edit source to update -->
-
-{% terminal(cmd="wt list") %}
-&#32;&#32;<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>
-@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>⇡3</span> <span class=d>6814f02a</span> <span class=d>30m</span> <span class=d>Add API tests</span>
-^ main <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=d>41ee0834</span> <span class=d>4d</span> <span class=d>Merge fix-auth: hardened to…</span>
-+ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=d>|</span> <span class=d>b772e68b</span> <span class=d>5h</span> <span class=d>Add secure token storage</span>
-+ <span class=d>fix-typos</span> <span class=d>_</span><span class=d>|</span> <span class=d>|</span> <span class=d>41ee0834</span> <span class=d>4d</span> <span class=d>Merge fix-auth: hardened to…</span>
-
-<span class=d>○</span> <span class=d>Showing 4 worktrees, 1 with changes, 2 ahead, 1 column hidden</span>
-{% end %}
-
-<!-- END AUTO-GENERATED -->
+<!-- wt list -->
+{{ terminal(cmd="wt list") }}
Include CI status, line diffs, and LLM summaries:
-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_list_full.snap — edit source to update -->
-
-{% terminal(cmd="wt list --full") %}
-&#32;&#32;<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Summary</b> <b>Remote⇅</b> <b>CI</b> <b>Commit</b>
-@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>+234</span> <span class=r>-24</span> Refactor API to REST architecture with middleware <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></span> <span class=d>6814f02a</span>
-^ main <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=g>●</span> <span class=d>41ee0834</span>
-+ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=g>+25</span> <span class=r>-11</span> Harden auth with constant-time token validation <span class=d>|</span> <span class=g>●</span> <span class=d>b772e68b</span>
-+ <span class=d>fix-typos</span> <span class=d>_</span><span class=d>|</span> <span class=d>|</span> <span class=g>●</span> <span class=d>41ee0834</span>
-
-<span class=d>○</span> <span class=d>Showing 4 worktrees, 1 with changes, 2 ahead, 3 columns hidden</span>
-{% end %}
-
-<!-- END AUTO-GENERATED -->
+<!-- wt list --full -->
+{{ terminal(cmd="wt list --full") }}
Include branches that don't have worktrees:
-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_list_branches.snap — edit source to update -->
-
-{% terminal(cmd="wt list --branches --full") %}
-&#32;&#32;<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Summary</b> <b>Remote⇅</b> <b>CI</b> <b>Commit</b>
-@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>+234</span> <span class=r>-24</span> Refactor API to REST architecture with middleware <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></span> <span class=d>6814f02a</span>
-^ main <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=g>●</span> <span class=d>41ee0834</span>
-+ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=g>+25</span> <span class=r>-11</span> Harden auth with constant-time token validation <span class=d>|</span> <span class=g>●</span> <span class=d>b772e68b</span>
-+ <span class=d>fix-typos</span> <span class=d>_</span><span class=d>|</span> <span class=d>|</span> <span class=g>●</span> <span class=d>41ee0834</span>
- exp <span class=d>/</span><span class=d>↕</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=g>+137</span> Explore GraphQL schema and resolvers <span class=d>96379229</span>
- wip <span class=d>/</span><span class=d>↕</span> <span class=g>↑1</span> <span class=d><span class=r>↓1</span></span> <span class=g>+33</span> Start API documentation <span class=d>b40716dc</span>
-
-<span class=d>○</span> <span class=d>Showing 4 worktrees, 2 branches, 1 with changes, 4 ahead, 3 columns hidden</span>
-{% end %}
-
-<!-- END AUTO-GENERATED -->
+<!-- wt list --branches --full -->
+{{ terminal(cmd="wt list --branches --full") }}
Output as JSON for scripting:
-```bash
-$ wt list --format=json
-```
+{{ terminal(cmd="wt list --format=json") }}
## Columns
@@ -173,31 +136,7 @@ These appear across all columns while the table is loading:
Query structured data with `--format=json`:
-```bash
-# Current worktree path (for scripts)
-wt list --format=json | jq -r '.[] | select(.is_current) | .path'
-
-# Branches with uncommitted changes
-wt list --format=json | jq '.[] | select(.working_tree.modified)'
-
-# Worktrees with merge conflicts
-wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
-
-# Branches ahead of main (needs merging)
-wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
-
-# Integrated branches (safe to remove)
-wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
-
-# Branches without worktrees
-wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
-
-# Worktrees ahead of remote (needs pushing)
-wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
-
-# Stale CI (local changes not reflected in CI)
-wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
-```
+{{ terminal(cmd="# Current worktree path (for scripts)|||wt list --format=json | jq -r '.[] | select(.is_current) | .path'||||||# Branches with uncommitted changes|||wt list --format=json | jq '.[] | select(.working_tree.modified)'||||||# Worktrees with merge conflicts|||wt list --format=json | jq '.[] | select(.operation_state == &quot;conflicts&quot;)'||||||# Branches ahead of main (needs merging)|||wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'||||||# Integrated branches (safe to remove)|||wt list --format=json | jq '.[] | select(.main_state == &quot;integrated&quot; or .main_state == &quot;empty&quot;) | .branch'||||||# Branches without worktrees|||wt list --format=json --branches | jq '.[] | select(.kind == &quot;branch&quot;) | .branch'||||||# Worktrees ahead of remote (needs pushing)|||wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'||||||# Stale CI (local changes not reflected in CI)|||wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'") }}
**Fields:**
diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.md
index e6194e8c5..d227cba10 100644
--- a/docs/content/llm-commits.md
+++ b/docs/content/llm-commits.md
@@ -74,17 +74,13 @@ Squashes all changes (uncommitted + existing commits) into one commit with an LL
Stages and commits with LLM-generated message:
-```bash
-$ wt step commit
-```
+{{ terminal(cmd="wt step commit") }}
### wt step squash
Squashes branch commits into one with LLM-generated message:
-```bash
-$ wt step squash
-```
+{{ terminal(cmd="wt step squash") }}
See [`wt merge`](@/merge.md) and [`wt step`](@/step.md) for full documentation.
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 1c6abefb3..0c02f2333 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -24,39 +24,27 @@ Unlike `git merge`, this merges the current branch into the target branch — no
Merge to the default branch:
-```bash
-wt merge
-```
+{{ terminal(cmd="wt merge") }}
Merge to a different branch:
-```bash
-wt merge develop
-```
+{{ terminal(cmd="wt merge develop") }}
Keep the worktree after merging:
-```bash
-wt merge --no-remove
-```
+{{ terminal(cmd="wt merge --no-remove") }}
Preserve commit history (no squash):
-```bash
-wt merge --no-squash
-```
+{{ terminal(cmd="wt merge --no-squash") }}
Create a merge commit — semi-linear history:
-```bash
-wt merge --no-ff
-```
+{{ terminal(cmd="wt merge --no-ff") }}
Skip committing/squashing (rebase still runs unless --no-rebase):
-```bash
-wt merge --no-commit
-```
+{{ terminal(cmd="wt merge --no-commit") }}
## Pipeline
diff --git a/docs/content/remove.md b/docs/content/remove.md
index d458c9da4..596e5d9aa 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -15,28 +15,19 @@ Remove worktree; delete branch if merged. Defaults to the current worktree.
Remove current worktree:
-```bash
-wt remove
-```
+{{ terminal(cmd="wt remove") }}
Remove specific worktrees / branches:
-```bash
-wt remove feature-branch
-wt remove old-feature another-branch
-```
+{{ terminal(cmd="wt remove feature-branch|||wt remove old-feature another-branch") }}
Keep the branch:
-```bash
-wt remove --no-delete-branch feature-branch
-```
+{{ terminal(cmd="wt remove --no-delete-branch feature-branch") }}
Force-delete an unmerged branch:
-```bash
-wt remove -D experimental
-```
+{{ terminal(cmd="wt remove -D experimental") }}
## Branch cleanup
@@ -63,11 +54,7 @@ Worktrunk has two force flags for different situations:
| `--force` (`-f`) | Worktree | Worktree has untracked files |
| `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
-```bash
-wt remove feature --force # Remove worktree with untracked files
-wt remove feature -D # Delete unmerged branch
-wt remove feature --force -D # Both
-```
+{{ terminal(cmd="wt remove feature --force # Remove worktree with untracked files|||wt remove feature -D # Delete unmerged branch|||wt remove feature --force -D # Both") }}
Without `--force`, removal fails if the worktree contains untracked files. Without `--force-delete`, removal keeps branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of merge status.
diff --git a/docs/content/step.md b/docs/content/step.md
index 2366d4a01..23dab158a 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -15,18 +15,11 @@ Run individual operations. The building blocks of wt merge — commit, squash, r
Commit with LLM-generated message:
-```bash
-wt step commit
-```
+{{ terminal(cmd="wt step commit") }}
Manual merge workflow with review between steps:
-```bash
-wt step commit
-wt step squash
-wt step rebase
-wt step push
-```
+{{ terminal(cmd="wt step commit|||wt step squash|||wt step rebase|||wt step push") }}
## Operations
@@ -106,9 +99,7 @@ Controls what to stage before committing:
| `tracked` | Stage only modified tracked files |
| `none` | Don't stage anything, commit only what's already staged |
-```bash
-wt step commit --stage=tracked
-```
+{{ terminal(cmd="wt step commit --stage=tracked") }}
Configure the default in user config:
@@ -121,13 +112,7 @@ stage = "tracked"
Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
-```bash
-# Inspect the rendered prompt
-wt step commit --show-prompt | less
-
-# Pipe to a different LLM
-wt step commit --show-prompt | llm -m gpt-5-nano
-```
+{{ terminal(cmd="# Inspect the rendered prompt|||wt step commit --show-prompt | less||||||# Pipe to a different LLM|||wt step commit --show-prompt | llm -m gpt-5-nano") }}
### Command reference
@@ -190,9 +175,7 @@ Controls what to stage before squashing:
| `tracked` | Stage only modified tracked files |
| `none` | Don't stage anything, squash only committed changes |
-```bash
-wt step squash --stage=none
-```
+{{ terminal(cmd="wt step squash --stage=none") }}
Configure the default in user config:
@@ -205,9 +188,7 @@ stage = "tracked"
Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
-```bash
-wt step squash --show-prompt | less
-```
+{{ terminal(cmd="wt step squash --show-prompt | less") }}
### Command reference
@@ -270,27 +251,17 @@ This is what `wt merge` would include — a single diff against the merge base.
Arguments after `--` are forwarded to `git diff`:
-```bash
-wt step diff -- --stat
-wt step diff -- --name-only
-wt step diff -- -- '*.rs'
-```
+{{ terminal(cmd="wt step diff -- --stat|||wt step diff -- --name-only|||wt step diff -- -- '*.rs'") }}
The diff is pipeable to tools like `delta`:
-```bash
-wt step diff | delta
-```
+{{ terminal(cmd="wt step diff | delta") }}
### How it works
Equivalent to:
-```bash
-cp "$(git rev-parse --git-dir)/index" /tmp/idx
-GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .
-GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))
-```
+{{ terminal(cmd="cp &quot;$(git rev-parse --git-dir)/index&quot; /tmp/idx|||GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .|||GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))") }}
`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.
@@ -470,40 +441,40 @@ All [hook template variables and filters](@/hook.md#template-variables) are avai
Get the port for the current branch:
-```bash
-$ wt step eval '{{ branch | hash_port }}'
+{% terminal() %}
+<span class="cmd">wt step eval '{{ branch | hash_port }}'</span>
16066
-```
+{% end %}
Use in shell substitution:
-```bash
-$ curl http://localhost:$(wt step eval '{{ branch | hash_port }}')/health
-```
+{% terminal() %}
+<span class="cmd">curl http://localhost:$(wt step eval '{{ branch | hash_port }}')/health</span>
+{% end %}
Combine multiple values:
-```bash
-$ wt step eval '{{ branch | hash_port }},{{ ("supabase-api-" ~ branch) | hash_port }}'
+{% terminal() %}
+<span class="cmd">wt step eval '{{ branch | hash_port }},{{ ("supabase-api-" ~ branch) | hash_port }}'</span>
16066,16739
-```
+{% end %}
Use conditionals and filters:
-```bash
-$ wt step eval '{{ branch | sanitize_db }}'
+{% terminal() %}
+<span class="cmd">wt step eval '{{ branch | sanitize_db }}'</span>
feature_auth_oauth2_a1b
-```
+{% end %}
Show available template variables:
-```bash
-$ wt step eval --dry-run '{{ branch }}'
+{% terminal() %}
+<span class="cmd">wt step eval --dry-run '{{ branch }}'</span>
branch=feature/auth-oauth2
worktree_path=/home/user/projects/myapp-feature-auth-oauth2
...
Result: feature/auth-oauth2
-```
+{% end %}
Note: This command is experimental and may change in future versions.
@@ -554,27 +525,21 @@ All variables are shell-escaped. See [`wt hook` template variables](@/hook.md#te
Check status across all worktrees:
-```bash
-wt step for-each -- git status --short
-```
+{{ terminal(cmd="wt step for-each -- git status --short") }}
Run npm install in all worktrees:
-```bash
-wt step for-each -- npm install
-```
+{{ terminal(cmd="wt step for-each -- npm install") }}
Use branch name in command:
-```bash
-wt step for-each -- "echo Branch: {{ branch }}"
-```
+{% terminal() %}
+<span class="cmd">wt step for-each -- "echo Branch: {{ branch }}"</span>
+{% end %}
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'
-```
+{{ terminal(cmd="git fetch --prune && wt step for-each -- '[ &quot;$(git rev-parse @{u} 2>/dev/null)&quot; ] || exit 0; git pull --autostash'") }}
Note: This command is experimental and may change in future versions.
@@ -616,10 +581,7 @@ Swap a branch into the main worktree. Exchanges branches and gitignored files be
### Example
-```bash
-# from ~/project (main worktree)
-$ wt step promote feature
-```
+{{ terminal(cmd="# from ~/project (main worktree)|||wt step promote feature") }}
Before:
@@ -698,24 +660,17 @@ Locked worktrees and the main worktree are always skipped. The current worktree
Worktrees younger than `--min-age` (default: 1 hour) are skipped. This prevents removing a worktree just created from the default branch — it looks "merged" because its branch points at the same commit.
-```bash
-wt step prune --min-age=0s # no age guard
-wt step prune --min-age=2d # skip worktrees younger than 2 days
-```
+{{ terminal(cmd="wt step prune --min-age=0s # no age guard|||wt step prune --min-age=2d # skip worktrees younger than 2 days") }}
### Examples
Preview what would be removed:
-```bash
-wt step prune --dry-run
-```
+{{ terminal(cmd="wt step prune --dry-run") }}
Remove all merged worktrees:
-```bash
-wt step prune
-```
+{{ terminal(cmd="wt step prune") }}
### Command reference
@@ -764,27 +719,19 @@ Move worktrees to expected paths. Relocates worktrees whose path doesn't match t
Preview what would be moved:
-```bash
-wt step relocate --dry-run
-```
+{{ terminal(cmd="wt step relocate --dry-run") }}
Move all mismatched worktrees:
-```bash
-wt step relocate
-```
+{{ terminal(cmd="wt step relocate") }}
Auto-commit and clobber blockers (never fails):
-```bash
-wt step relocate --commit --clobber
-```
+{{ terminal(cmd="wt step relocate --commit --clobber") }}
Move specific worktrees:
-```bash
-wt step relocate feature bugfix
-```
+{{ terminal(cmd="wt step relocate feature bugfix") }}
### Swap handling
@@ -864,12 +811,7 @@ deploy = "make deploy BRANCH={{ branch }}"
port = "echo http://localhost:{{ branch | hash_port }}"
```
-```bash
-wt step deploy # run the alias
-wt step deploy --dry-run # show expanded command
-wt step deploy --var env=staging # pass extra template variables
-wt step deploy --yes # skip approval prompt
-```
+{{ terminal(cmd="wt step deploy # run the alias|||wt step deploy --dry-run # show expanded command|||wt step deploy --var env=staging # pass extra template variables|||wt step deploy --yes # skip approval prompt") }}
When defined in both user and project config, both run — user first, then project. Project-config aliases require [command approval](@/hook.md#wt-hook-approvals) on first run, same as project hooks. User-config aliases are trusted.
diff --git a/docs/content/switch.md b/docs/content/switch.md
index e29c99596..ae56a6951 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -22,13 +22,7 @@ Worktrees are addressed by branch name; paths are computed from a configurable t
## Examples
-```bash
-wt switch feature-auth # Switch to worktree
-wt switch - # Previous worktree (like cd -)
-wt switch --create new-feature # Create new branch and worktree
-wt switch --create hotfix --base production
-wt switch pr:123 # Switch to PR #123's branch
-```
+{{ terminal(cmd="wt switch feature-auth # Switch to worktree|||wt switch - # Previous worktree (like cd -)|||wt switch --create new-feature # Create new branch and worktree|||wt switch --create hotfix --base production|||wt switch pr:123 # Switch to PR #123's branch") }}
## Creating a branch
@@ -44,12 +38,7 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth
4. Runs [pre-start hooks](@/hook.md#pre-start), blocking until complete
5. Spawns [post-start](@/hook.md#post-start) and [post-switch hooks](@/hook.md#post-switch) in the background
-```bash
-wt switch feature # Existing branch → creates worktree
-wt switch --create feature # New branch and worktree
-wt switch --create fix --base release # New branch from release
-wt switch --create temp --no-verify # Skip hooks
-```
+{{ terminal(cmd="wt switch feature # Existing branch → creates worktree|||wt switch --create feature # New branch and worktree|||wt switch --create fix --base release # New branch from release|||wt switch --create temp --no-verify # Skip hooks") }}
## Shortcuts
@@ -61,13 +50,7 @@ wt switch --create temp --no-verify # Skip hooks
| `pr:{N}` | GitHub PR #N's branch |
| `mr:{N}` | GitLab MR !N's branch |
-```bash
-wt switch - # Back to previous
-wt switch ^ # Default branch worktree
-wt switch --create fix --base=@ # Branch from current HEAD
-wt switch pr:123 # PR #123's branch
-wt switch mr:101 # MR !101's branch
-```
+{{ terminal(cmd="wt switch - # Back to previous|||wt switch ^ # Default branch worktree|||wt switch --create fix --base=@ # Branch from current HEAD|||wt switch pr:123 # PR #123's branch|||wt switch mr:101 # MR !101's branch") }}
## Interactive picker
@@ -114,10 +97,7 @@ Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch <
The `pr:<number>` and `mr:<number>` shortcuts resolve a GitHub PR or GitLab MR to its branch. For same-repo PRs/MRs, worktrunk switches to the branch directly. For fork PRs/MRs, it fetches the ref (`refs/pull/N/head` or `refs/merge-requests/N/head`) and configures `pushRemote` to the fork URL.
-```bash
-wt switch pr:101 # GitHub PR #101
-wt switch mr:101 # GitLab MR !101
-```
+{{ terminal(cmd="wt switch pr:101 # GitHub PR #101|||wt switch mr:101 # GitLab MR !101") }}
Requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated. The `--create` flag cannot be used with `pr:`/`mr:` syntax since the branch already exists.
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 71367be16..dfa763808 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -13,11 +13,7 @@ Practical recipes for common Worktrunk workflows.
Create a worktree and launch Claude in one command:
-```bash
-alias wsc='wt switch --create --execute=claude'
-wsc new-feature # Creates worktree, runs hooks, launches Claude
-wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`
-```
+{{ terminal(cmd="alias wsc='wt switch --create --execute=claude'|||wsc new-feature # Creates worktree, runs hooks, launches Claude|||wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`") }}
## Eliminate cold starts
@@ -151,19 +147,13 @@ Custom emoji markers show agent state in `wt list`. The Claude Code plugin sets
Set status manually for any workflow:
-```bash
-wt config state marker set "🚧" # Current branch
-wt config state marker set "✅" --branch feature # Specific branch
-git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct
-```
+{{ terminal(cmd="wt config state marker set &quot;🚧&quot; # Current branch|||wt config state marker set &quot;✅&quot; --branch feature # Specific branch|||git config worktrunk.state.feature.marker '{&quot;marker&quot;:&quot;💬&quot;,&quot;set_at&quot;:0}' # Direct") }}
See [Claude Code Integration](@/claude-code.md#installation) for plugin installation.
## Monitor CI across branches
-```bash
-wt list --full --branches
-```
+{{ terminal(cmd="wt list --full --branches") }}
Shows PR/CI status for all branches, including those without worktrees. CI indicators are clickable links to the PR page.
@@ -181,9 +171,7 @@ Summaries are cached and regenerated only when the diff changes. See [LLM Commit
## JSON API
-```bash
-wt list --format=json
-```
+{{ terminal(cmd="wt list --format=json") }}
Structured output for dashboards, statuslines, and scripts. See [`wt list`](@/list.md) for query examples.
@@ -191,9 +179,7 @@ Structured output for dashboards, statuslines, and scripts. See [`wt list`](@/li
Worktrunk maintains useful state. Default branch [detection](@/config.md#wt-config-state-default-branch), for instance, means scripts work on any repo — no need to hardcode `main` or `master`:
-```bash
-git rebase $(wt config state default-branch)
-```
+{{ terminal(cmd="git rebase $(wt config state default-branch)") }}
## Task runners in hooks
@@ -211,19 +197,13 @@ Reference Taskfile/Justfile/Makefile in hooks:
Special arguments work across all commands—see [`wt switch`](@/switch.md#shortcuts) for the full list.
-```bash
-wt switch --create hotfix --base=@ # Branch from current HEAD
-wt switch - # Switch to previous worktree
-wt remove @ # Remove current worktree
-```
+{{ terminal(cmd="wt switch --create hotfix --base=@ # Branch from current HEAD|||wt switch - # Switch to previous worktree|||wt remove @ # Remove current worktree") }}
## Stacked branches
Branch from current HEAD instead of the default branch:
-```bash
-wt switch --create feature-part2 --base=@
-```
+{{ terminal(cmd="wt switch --create feature-part2 --base=@") }}
Creates a worktree that builds on the current branch's changes.
@@ -232,16 +212,10 @@ Creates a worktree that builds on the current branch's changes.
Spawn a worktree with Claude running in the background:
**tmux** (new detached session):
-```bash
-tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
- 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"
-```
+{{ terminal(cmd="tmux new-session -d -s fix-auth-bug &quot;wt switch --create fix-auth-bug -x claude -- \||| 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'&quot;") }}
**Zellij** (new pane in current session):
-```bash
-zellij run -- wt switch --create fix-auth-bug -x claude -- \
- 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'
-```
+{{ terminal(cmd="zellij run -- wt switch --create fix-auth-bug -x claude -- \||| 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'") }}
This lets one Claude session hand off work to another that runs in the background. Hooks run inside the multiplexer session/pane.
@@ -286,9 +260,9 @@ tmux = "tmux kill-session -t {{ branch | sanitize }} 2>/dev/null || true"
To create a worktree and immediately attach:
-```bash
-wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'
-```
+{% terminal() %}
+<span class="cmd">wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'</span>
+{% end %}
## Xcode DerivedData cleanup
@@ -349,17 +323,13 @@ url = "http://{{ branch | sanitize }}.{{ repo }}.localhost:8080"
Follow background hook output in real-time:
-```bash
-tail -f "$(wt config state logs get --hook=user:post-start:server)"
-```
+{{ terminal(cmd="tail -f &quot;$(wt config state logs get --hook=user:post-start:server)&quot;") }}
The `--hook` format is `source:hook-type:name` — e.g., `project:post-start:build` for project-defined hooks. Use `wt config state logs get` to list all available logs.
Create an alias for frequent use:
-```bash
-alias wtlog='f() { tail -f "$(wt config state logs get --hook="$1")"; }; f'
-```
+{{ terminal(cmd="alias wtlog='f() { tail -f &quot;$(wt config state logs get --hook=&quot;$1&quot;)&quot;; }; f'") }}
## Bare repository layout
@@ -367,10 +337,7 @@ A [bare repository](https://git-scm.com/docs/gitrepository-layout) has no workin
Cloning a bare repo into `<project>/.git` puts all worktrees under one directory:
-```bash
-git clone --bare <url> myproject/.git
-cd myproject
-```
+{{ terminal(cmd="git clone --bare <url> myproject/.git|||cd myproject") }}
With `worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"`, worktrees become subdirectories of `myproject/`:
@@ -391,8 +358,6 @@ worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"
Create the first worktree:
-```bash
-wt switch --create main
-```
+{{ terminal(cmd="wt switch --create main") }}
Now `wt switch --create feature` creates `myproject/feature/`.
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index b44894d52..6445cd8ee 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -107,27 +107,20 @@ A demo with some advanced features:
**Homebrew (macOS & Linux):**
-```bash
-brew install worktrunk && wt config shell install
-```
+{{ terminal(cmd="brew install worktrunk && wt config shell install") }}
Shell integration allows commands to change directories.
**Cargo:**
-```bash
-cargo install worktrunk && wt config shell install
-```
+{{ terminal(cmd="cargo install worktrunk && wt config shell install") }}
<details>
<summary><strong>Windows</strong></summary>
On Windows, `wt` defaults to Windows Terminal's command. Winget additionally installs Worktrunk as `git-wt` to avoid the conflict:
-```bash
-winget install max-sixty.worktrunk
-git-wt config shell install
-```
+{{ terminal(cmd="winget install max-sixty.worktrunk|||git-wt config shell install") }}
Alternatively, disable Windows Terminal's alias (Settings → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal") to use `wt` directly.
@@ -135,9 +128,7 @@ Alternatively, disable Windows Terminal's alias (Settings → Privacy & security
**Arch Linux:**
-```bash
-paru worktrunk-bin && wt config shell install
-```
+{{ terminal(cmd="paru worktrunk-bin && wt config shell install") }}
## Quick start
@@ -173,11 +164,7 @@ When done, either:
**PR workflow** — commit, push, open a PR, merge via GitHub/GitLab, then clean up:
-```bash
-wt step commit # commit staged changes
-gh pr create # or glab mr create
-wt remove # after PR is merged
-```
+{{ terminal(cmd="wt step commit # commit staged changes|||gh pr create # or glab mr create|||wt remove # after PR is merged") }}
**Local merge** — squash, rebase onto main, fast-forward merge, clean up:
@@ -202,11 +189,7 @@ wt remove # after PR is merged
For parallel agents, create multiple worktrees and launch an agent in each:
-```bash
-wt switch -x claude -c feature-a -- 'Add user authentication'
-wt switch -x claude -c feature-b -- 'Fix the pagination bug'
-wt switch -x claude -c feature-c -- 'Write tests for the API'
-```
+{{ terminal(cmd="wt switch -x claude -c feature-a -- 'Add user authentication'|||wt switch -x claude -c feature-b -- 'Fix the pagination bug'|||wt switch -x claude -c feature-c -- 'Write tests for the API'") }}
The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](@/hook.md) to automate setup (install deps, start dev servers).
diff --git a/docs/templates/shortcodes/terminal.html b/docs/templates/shortcodes/terminal.html
index 340917dd5..c70593ffb 100644
--- a/docs/templates/shortcodes/terminal.html
+++ b/docs/templates/shortcodes/terminal.html
@@ -1,12 +1,24 @@
{% if cmd %}
{% set fence = "```" %}
-{% set md = fence ~ "bash
-" ~ cmd ~ "
-" ~ fence %}
-{% set raw = md | markdown %}
-{% set hl = raw | regex_replace(pattern="(?s)<pre[^>]*><code[^>]*>(.*)</code>\s*</pre>", rep="$1") | trim %}
+{% set cmd_lines = cmd | split(pat="|||") %}
+{% if body is defined %}
{% set clean_body = body | regex_replace(pattern='<span class="cmd">[^<]*</span>\n?', rep="") %}
-<pre class="terminal"><code><span class="cmd">{{ hl | safe }}</span>
+{% else %}
+{% set clean_body = "" %}
+{% endif %}
+<pre class="terminal"><code>
+{%- for cmd_line in cmd_lines -%}
+{%- set md = fence ~ "bash
+" ~ cmd_line ~ "
+" ~ fence -%}
+{%- set raw = md | markdown -%}
+{%- set hl = raw | regex_replace(pattern="(?s)<pre[^>]*><code[^>]*>(.*)</code>\s*</pre>", rep="$1") | trim -%}
+{%- if cmd_line is starting_with("#") -%}
+{{ hl | safe }}
+{% else -%}
+<span class="cmd">{{ hl | safe }}</span>
+{% endif -%}
+{%- endfor -%}
{{ clean_body | safe }}</code></pre>
{% else %}
<pre class="terminal"><code>{{ body | safe }}</code></pre>
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index fe8515c54..4255b4737 100644
--- a/skills/worktrunk/reference/claude-code.md
+++ b/skills/worktrunk/reference/claude-code.md
@@ -7,10 +7,8 @@ The worktrunk Claude Code plugin provides two features:
## Installation
-```bash
-$ claude plugin marketplace add max-sixty/worktrunk
-$ claude plugin install worktrunk@worktrunk
-```
+<span class="cmd">claude plugin marketplace add max-sixty/worktrunk</span>
+<span class="cmd">claude plugin install worktrunk@worktrunk</span>
## Configuration skill
@@ -27,7 +25,6 @@ Claude Code is designed to load the skill automatically when it detects worktrun
The plugin tracks Claude sessions with status markers in `wt list`:
-{% terminal(cmd="wt list") %}
<span class="cmd">wt list</span>
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>Path</b> <b>Commit</b> <b>Age</b> <b>Message</b>
@ main <span class=d>^</span><span class=d>⇡</span> <span class=g>⇡1</span> . <span class=d>33323bc1</span> <span class=d>1d</span> <span class=d>Initial commit</span>
@@ -36,7 +33,6 @@ The plugin tracks Claude sessions with status markers in `wt list`:
+ wip-docs <span class=c>?</span> <span class=d>–</span> ../repo.wip-docs <span class=d>33323bc1</span> <span class=d>1d</span> <span class=d>Initial commit</span>
<span class=d>○</span> <span class=d>Showing 4 worktrees, 2 with changes, 2 ahead</span>
-{% end %}
- 🤖 — Claude is working
- 💬 — Claude is waiting for input
@@ -45,11 +41,9 @@ The plugin tracks Claude sessions with status markers in `wt list`:
Set status markers manually for any workflow:
-```bash
-$ wt config state marker set "🚧" # Current branch
-$ wt config state marker set "✅" --branch feature # Specific branch
-$ git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct
-```
+<span class="cmd">wt config state marker set "🚧" # Current branch</span>
+<span class="cmd">wt config state marker set "✅" --branch feature # Specific branch</span>
+<span class="cmd">git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct</span>
## Statusline
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 91d98476e..4b928024c 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -7,25 +7,25 @@ Manage user & project configs. Includes shell integration, hooks, and saved stat
Install shell integration (required for directory switching):
```bash
-wt config shell install
+$ wt config shell install
```
Create user config file with documented examples:
```bash
-wt config create
+$ wt config create
```
Create project config file (`.config/wt.toml`) for hooks:
```bash
-wt config create --project
+$ wt config create --project
```
Show current configuration and file locations:
```bash
-wt config show
+$ wt config show
```
## Configuration files
@@ -375,7 +375,7 @@ test = "cargo test"
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
```bash
-wt config shell install
+$ wt config shell install
```
For manual setup, see `wt config shell init --help`.
@@ -411,7 +411,7 @@ Note the single underscore after `WORKTRUNK` and double underscores between nest
Override the LLM command in CI to use a mock:
```bash
-WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
+$ WORKTRUNK_COMMIT__GENERATION__COMMAND=&quot;echo 'test: automated commit'&quot; wt merge
```
### Other environment variables
@@ -473,7 +473,7 @@ If a config file doesn't exist, shows defaults that would be used.
Use `--full` to run diagnostic checks:
```bash
-wt config show --full
+$ wt config show --full
```
This tests:
@@ -523,32 +523,32 @@ Use `wt config show` to view file-based configuration.
Get the default branch:
```bash
-wt config state default-branch
+$ wt config state default-branch
```
Set the default branch manually:
```bash
-wt config state default-branch set main
+$ wt config state default-branch set main
```
Set a marker for current branch:
```bash
-wt config state marker set "🚧 WIP"
+$ wt config state marker set &quot;🚧 WIP&quot;
```
Clear all CI status cache:
```bash
-wt config state ci-status clear --all
+$ wt config state ci-status clear --all
```
Show all stored state:
```bash
-wt config state get
+$ wt config state get
```
Clear all stored state:
```bash
-wt config state clear
+$ wt config state clear
```
### Command reference
@@ -714,7 +714,7 @@ bugfix 🤖!↑⇡ ~/code/myproject.bugfix
Stored in git config as `worktrunk.state.<branch>.marker`. Set directly with:
```bash
-git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
+$ git config worktrunk.state.feature.marker '{&quot;marker&quot;:&quot;🚧&quot;,&quot;set_at&quot;:0}'
```
Without a subcommand, runs `get` for the current branch. For `--branch`, use `get --branch=NAME`.
@@ -781,22 +781,22 @@ All logs are stored in `.git/wt/logs/` (in the main worktree's git directory).
List all log files:
```bash
-wt config state logs get
+$ wt config state logs get
```
Query the command log:
```bash
-tail -5 .git/wt/logs/commands.jsonl | jq .
+$ tail -5 .git/wt/logs/commands.jsonl | jq .
```
View a specific hook log:
```bash
-cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"
+$ cat &quot;$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log&quot;
```
Clear all logs:
```bash
-wt config state logs clear
+$ wt config state logs clear
```
### Command reference
diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
index 7367c982a..4f4f97760 100644
--- a/skills/worktrunk/reference/faq.md
+++ b/skills/worktrunk/reference/faq.md
@@ -10,24 +10,20 @@ Branch switching uses one directory: uncommitted changes from one agent get mixe
Git's built-in worktree commands work but require manual lifecycle management:
-```bash
# Plain git worktree workflow
-git worktree add -b feature-branch ../myapp-feature main
-cd ../myapp-feature
+<span class="cmd">git worktree add -b feature-branch ../myapp-feature main</span>
+<span class="cmd">cd ../myapp-feature</span>
# ...work, commit, push...
-cd ../myapp
-git merge feature-branch
-git worktree remove ../myapp-feature
-git branch -d feature-branch
-```
+<span class="cmd">cd ../myapp</span>
+<span class="cmd">git merge feature-branch</span>
+<span class="cmd">git worktree remove ../myapp-feature</span>
+<span class="cmd">git branch -d feature-branch</span>
Worktrunk automates the full lifecycle:
-```bash
-wt switch --create feature-branch # Creates worktree, runs setup hooks
+<span class="cmd">wt switch --create feature-branch # Creates worktree, runs setup hooks</span>
# ...work...
-wt merge # Merges into default branch, cleans up
-```
+<span class="cmd">wt merge # Merges into default branch, cleans up</span>
No cd back to main — `wt merge` runs from the feature worktree and merges into the target, like GitHub's merge button.
@@ -132,9 +128,7 @@ Worktrunk can delete **worktrees** and **branches**. Both have safeguards.
For worktrees containing precious ignored data (databases, caches, large assets), use `git worktree lock`:
-```bash
-git worktree lock ../myproject.feature --reason "Contains local database"
-```
+{{ terminal(cmd="git worktree lock ../myproject.feature --reason \"Contains local database\"") }}
Locked worktrees show `⊞` in `wt list`. Neither `git worktree remove` nor `wt remove` (even with `--force`) will delete them. Unlock with `git worktree unlock`.
@@ -185,13 +179,11 @@ All hook executions and LLM commands are recorded in `.git/wt/logs/commands.json
View the log with `wt config state logs get`, or query directly:
-```bash
# Recent commands
-tail -5 .git/wt/logs/commands.jsonl | jq .
+<span class="cmd">tail -5 .git/wt/logs/commands.jsonl | jq .</span>
# Failed commands
-jq 'select(.exit != 0 and .exit != null)' .git/wt/logs/commands.jsonl
-```
+<span class="cmd">jq 'select(.exit != 0 and .exit != null)' .git/wt/logs/commands.jsonl</span>
Clear with `wt config state logs clear`.
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index a978f7aa9..df1c7df18 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -276,14 +276,7 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:
`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.
```bash
-wt hook pre-merge # Run all pre-merge hooks
-wt hook pre-merge test # Run hooks named "test" from both sources
-wt hook pre-merge user: # Run all user hooks
-wt hook pre-merge project: # Run all project hooks
-wt hook pre-merge user:test # Run only user's "test" hook
-wt hook pre-merge project:test # Run only project's "test" hook
-wt hook pre-merge --yes # Skip approval prompts (for CI)
-wt hook pre-start --var branch=feature/test # Override template variable
+$ wt hook pre-merge # Run all pre-merge hooks|||wt hook pre-merge test # Run hooks named &quot;test&quot; from both sources|||wt hook pre-merge user: # Run all user hooks|||wt hook pre-merge project: # Run all project hooks|||wt hook pre-merge user:test # Run only user's &quot;test&quot; hook|||wt hook pre-merge project:test # Run only project's &quot;test&quot; hook|||wt hook pre-merge --yes # Skip approval prompts (for CI)|||wt hook pre-start --var branch=feature/test # Override template variable
```
The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.
@@ -527,17 +520,17 @@ Project hooks require approval on first run to prevent untrusted projects from r
Pre-approve all commands for current project:
```bash
-wt hook approvals add
+$ wt hook approvals add
```
Clear approvals for current project:
```bash
-wt hook approvals clear
+$ wt hook approvals clear
```
Clear global approvals:
```bash
-wt hook approvals clear --global
+$ wt hook approvals clear --global
```
### How approvals work
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index 82891b4e7..9766fda59 100644
--- a/skills/worktrunk/reference/list.md
+++ b/skills/worktrunk/reference/list.md
@@ -14,41 +14,24 @@ The table renders progressively: branch names, paths, and commit hashes appear i
List all worktrees:
-{% terminal(cmd="wt list") %}
-&#32;&#32;<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>
-@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>⇡3</span> <span class=d>6814f02a</span> <span class=d>30m</span> <span class=d>Add API tests</span>
-^ main <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=d>41ee0834</span> <span class=d>4d</span> <span class=d>Merge fix-auth: hardened to…</span>
-+ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=d>|</span> <span class=d>b772e68b</span> <span class=d>5h</span> <span class=d>Add secure token storage</span>
-+ <span class=d>fix-typos</span> <span class=d>_</span><span class=d>|</span> <span class=d>|</span> <span class=d>41ee0834</span> <span class=d>4d</span> <span class=d>Merge fix-auth: hardened to…</span>
-
-<span class=d>○</span> <span class=d>Showing 4 worktrees, 1 with changes, 2 ahead, 1 column hidden</span>
-{% end %}
+<!-- wt list -->
+```bash
+$ wt list
+```
Include CI status, line diffs, and LLM summaries:
-{% terminal(cmd="wt list --full") %}
-&#32;&#32;<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Summary</b> <b>Remote⇅</b> <b>CI</b> <b>Commit</b>
-@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>+234</span> <span class=r>-24</span> Refactor API to REST architecture with middleware <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></span> <span class=d>6814f02a</span>
-^ main <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=g>●</span> <span class=d>41ee0834</span>
-+ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=g>+25</span> <span class=r>-11</span> Harden auth with constant-time token validation <span class=d>|</span> <span class=g>●</span> <span class=d>b772e68b</span>
-+ <span class=d>fix-typos</span> <span class=d>_</span><span class=d>|</span> <span class=d>|</span> <span class=g>●</span> <span class=d>41ee0834</span>
-
-<span class=d>○</span> <span class=d>Showing 4 worktrees, 1 with changes, 2 ahead, 3 columns hidden</span>
-{% end %}
+<!-- wt list --full -->
+```bash
+$ wt list --full
+```
Include branches that don't have worktrees:
-{% terminal(cmd="wt list --branches --full") %}
-&#32;&#32;<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Summary</b> <b>Remote⇅</b> <b>CI</b> <b>Commit</b>
-@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>+234</span> <span class=r>-24</span> Refactor API to REST architecture with middleware <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></span> <span class=d>6814f02a</span>
-^ main <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=g>●</span> <span class=d>41ee0834</span>
-+ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=g>+25</span> <span class=r>-11</span> Harden auth with constant-time token validation <span class=d>|</span> <span class=g>●</span> <span class=d>b772e68b</span>
-+ <span class=d>fix-typos</span> <span class=d>_</span><span class=d>|</span> <span class=d>|</span> <span class=g>●</span> <span class=d>41ee0834</span>
- exp <span class=d>/</span><span class=d>↕</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> <span class=g>+137</span> Explore GraphQL schema and resolvers <span class=d>96379229</span>
- wip <span class=d>/</span><span class=d>↕</span> <span class=g>↑1</span> <span class=d><span class=r>↓1</span></span> <span class=g>+33</span> Start API documentation <span class=d>b40716dc</span>
-
-<span class=d>○</span> <span class=d>Showing 4 worktrees, 2 branches, 1 with changes, 4 ahead, 3 columns hidden</span>
-{% end %}
+<!-- wt list --branches --full -->
+```bash
+$ wt list --branches --full
+```
Output as JSON for scripting:
@@ -146,29 +129,7 @@ These appear across all columns while the table is loading:
Query structured data with `--format=json`:
```bash
-# Current worktree path (for scripts)
-wt list --format=json | jq -r '.[] | select(.is_current) | .path'
-
-# Branches with uncommitted changes
-wt list --format=json | jq '.[] | select(.working_tree.modified)'
-
-# Worktrees with merge conflicts
-wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
-
-# Branches ahead of main (needs merging)
-wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
-
-# Integrated branches (safe to remove)
-wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
-
-# Branches without worktrees
-wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
-
-# Worktrees ahead of remote (needs pushing)
-wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
-
-# Stale CI (local changes not reflected in CI)
-wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
+$ # Current worktree path (for scripts)|||wt list --format=json | jq -r '.[] | select(.is_current) | .path'||||||# Branches with uncommitted changes|||wt list --format=json | jq '.[] | select(.working_tree.modified)'||||||# Worktrees with merge conflicts|||wt list --format=json | jq '.[] | select(.operation_state == &quot;conflicts&quot;)'||||||# Branches ahead of main (needs merging)|||wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'||||||# Integrated branches (safe to remove)|||wt list --format=json | jq '.[] | select(.main_state == &quot;integrated&quot; or .main_state == &quot;empty&quot;) | .branch'||||||# Branches without worktrees|||wt list --format=json --branches | jq '.[] | select(.kind == &quot;branch&quot;) | .branch'||||||# Worktrees ahead of remote (needs pushing)|||wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'||||||# Stale CI (local changes not reflected in CI)|||wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
```
**Fields:**
diff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.md
index 0321c0ac0..1ceb1966d 100644
--- a/skills/worktrunk/reference/llm-commits.md
+++ b/skills/worktrunk/reference/llm-commits.md
@@ -49,12 +49,10 @@ These examples assume a feature worktree with changes to commit.
Squashes all changes (uncommitted + existing commits) into one commit with an LLM-generated message, then merges to the default branch:
-{% terminal(cmd="wt merge") %}
<span class=c>◎</span> <span class=c>Squashing 3 commits into a single commit <span style='color:var(--bright-black,#555)'>(5 files, <span class=g>+48</span></span></span><span style='color:var(--bright-black,#555)'>)</span>...
<span class=c>◎</span> <span class=c>Generating squash commit message...</span>
<span style='background:var(--bright-white,#fff)'> </span> <b>feat(auth): Implement JWT authentication system</b>
<span style='background:var(--bright-white,#fff)'> </span> ...
-{% end %}
### wt step commit
diff --git a/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.md
index 251b48947..f7be30718 100644
--- a/skills/worktrunk/reference/merge.md
+++ b/skills/worktrunk/reference/merge.md
@@ -9,37 +9,37 @@ Unlike `git merge`, this merges the current branch into the target branch — no
Merge to the default branch:
```bash
-wt merge
+$ wt merge
```
Merge to a different branch:
```bash
-wt merge develop
+$ wt merge develop
```
Keep the worktree after merging:
```bash
-wt merge --no-remove
+$ wt merge --no-remove
```
Preserve commit history (no squash):
```bash
-wt merge --no-squash
+$ wt merge --no-squash
```
Create a merge commit — semi-linear history:
```bash
-wt merge --no-ff
+$ wt merge --no-ff
```
Skip committing/squashing (rebase still runs unless --no-rebase):
```bash
-wt merge --no-commit
+$ wt merge --no-commit
```
## Pipeline
diff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.md
index 14cfe0cc1..c1dfd1226 100644
--- a/skills/worktrunk/reference/remove.md
+++ b/skills/worktrunk/reference/remove.md
@@ -7,26 +7,25 @@ Remove worktree; delete branch if merged. Defaults to the current worktree.
Remove current worktree:
```bash
-wt remove
+$ wt remove
```
Remove specific worktrees / branches:
```bash
-wt remove feature-branch
-wt remove old-feature another-branch
+$ wt remove feature-branch|||wt remove old-feature another-branch
```
Keep the branch:
```bash
-wt remove --no-delete-branch feature-branch
+$ wt remove --no-delete-branch feature-branch
```
Force-delete an unmerged branch:
```bash
-wt remove -D experimental
+$ wt remove -D experimental
```
## Branch cleanup
@@ -55,9 +54,7 @@ Worktrunk has two force flags for different situations:
| `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
```bash
-wt remove feature --force # Remove worktree with untracked files
-wt remove feature -D # Delete unmerged branch
-wt remove feature --force -D # Both
+$ wt remove feature --force # Remove worktree with untracked files|||wt remove feature -D # Delete unmerged branch|||wt remove feature --force -D # Both
```
Without `--force`, removal fails if the worktree contains untracked files. Without `--force-delete`, removal keeps branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of merge status.
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index c2911a4a2..0e3e0b7ca 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -7,16 +7,13 @@ Run individual operations. The building blocks of wt merge — commit, squash, r
Commit with LLM-generated message:
```bash
-wt step commit
+$ wt step commit
```
Manual merge workflow with review between steps:
```bash
-wt step commit
-wt step squash
-wt step rebase
-wt step push
+$ wt step commit|||wt step squash|||wt step rebase|||wt step push
```
## Operations
@@ -91,7 +88,7 @@ Controls what to stage before committing:
| `none` | Don't stage anything, commit only what's already staged |
```bash
-wt step commit --stage=tracked
+$ wt step commit --stage=tracked
```
Configure the default in user config:
@@ -106,11 +103,7 @@ stage = "tracked"
Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
```bash
-# Inspect the rendered prompt
-wt step commit --show-prompt | less
-
-# Pipe to a different LLM
-wt step commit --show-prompt | llm -m gpt-5-nano
+$ # Inspect the rendered prompt|||wt step commit --show-prompt | less||||||# Pipe to a different LLM|||wt step commit --show-prompt | llm -m gpt-5-nano
```
### Command reference
@@ -173,7 +166,7 @@ Controls what to stage before squashing:
| `none` | Don't stage anything, squash only committed changes |
```bash
-wt step squash --stage=none
+$ wt step squash --stage=none
```
Configure the default in user config:
@@ -188,7 +181,7 @@ stage = "tracked"
Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
```bash
-wt step squash --show-prompt | less
+$ wt step squash --show-prompt | less
```
### Command reference
@@ -251,15 +244,13 @@ This is what `wt merge` would include — a single diff against the merge base.
Arguments after `--` are forwarded to `git diff`:
```bash
-wt step diff -- --stat
-wt step diff -- --name-only
-wt step diff -- -- '*.rs'
+$ wt step diff -- --stat|||wt step diff -- --name-only|||wt step diff -- -- '*.rs'
```
The diff is pipeable to tools like `delta`:
```bash
-wt step diff | delta
+$ wt step diff | delta
```
### How it works
@@ -267,9 +258,7 @@ wt step diff | delta
Equivalent to:
```bash
-cp "$(git rev-parse --git-dir)/index" /tmp/idx
-GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .
-GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))
+$ cp &quot;$(git rev-parse --git-dir)/index&quot; /tmp/idx|||GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .|||GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))
```
`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.
@@ -446,40 +435,30 @@ All [hook template variables and filters](https://worktrunk.dev/hook/#template-v
Get the port for the current branch:
-```bash
-$ wt step eval '{{ branch | hash_port }}'
+<span class="cmd">wt step eval '{{ branch | hash_port }}'</span>
16066
-```
Use in shell substitution:
-```bash
-$ curl http://localhost:$(wt step eval '{{ branch | hash_port }}')/health
-```
+<span class="cmd">curl http://localhost:$(wt step eval '{{ branch | hash_port }}')/health</span>
Combine multiple values:
-```bash
-$ wt step eval '{{ branch | hash_port }},{{ ("supabase-api-" ~ branch) | hash_port }}'
+<span class="cmd">wt step eval '{{ branch | hash_port }},{{ ("supabase-api-" ~ branch) | hash_port }}'</span>
16066,16739
-```
Use conditionals and filters:
-```bash
-$ wt step eval '{{ branch | sanitize_db }}'
+<span class="cmd">wt step eval '{{ branch | sanitize_db }}'</span>
feature_auth_oauth2_a1b
-```
Show available template variables:
-```bash
-$ wt step eval --dry-run '{{ branch }}'
+<span class="cmd">wt step eval --dry-run '{{ branch }}'</span>
branch=feature/auth-oauth2
worktree_path=/home/user/projects/myapp-feature-auth-oauth2
...
Result: feature/auth-oauth2
-```
Note: This command is experimental and may change in future versions.
@@ -529,25 +508,23 @@ All variables are shell-escaped. See [`wt hook` template variables](https://work
Check status across all worktrees:
```bash
-wt step for-each -- git status --short
+$ wt step for-each -- git status --short
```
Run npm install in all worktrees:
```bash
-wt step for-each -- npm install
+$ wt step for-each -- npm install
```
Use branch name in command:
-```bash
-wt step for-each -- "echo Branch: {{ branch }}"
-```
+<span class="cmd">wt step for-each -- "echo Branch: {{ branch }}"</span>
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'
+$ git fetch --prune && wt step for-each -- '[ &quot;$(git rev-parse @{u} 2>/dev/null)&quot; ] || exit 0; git pull --autostash'
```
Note: This command is experimental and may change in future versions.
@@ -589,8 +566,7 @@ Swap a branch into the main worktree. Exchanges branches and gitignored files be
### Example
```bash
-# from ~/project (main worktree)
-$ wt step promote feature
+$ # from ~/project (main worktree)|||wt step promote feature
```
Before:
@@ -669,8 +645,7 @@ Locked worktrees and the main worktree are always skipped. The current worktree
Worktrees younger than `--min-age` (default: 1 hour) are skipped. This prevents removing a worktree just created from the default branch — it looks "merged" because its branch points at the same commit.
```bash
-wt step prune --min-age=0s # no age guard
-wt step prune --min-age=2d # skip worktrees younger than 2 days
+$ wt step prune --min-age=0s # no age guard|||wt step prune --min-age=2d # skip worktrees younger than 2 days
```
### Examples
@@ -678,13 +653,13 @@ wt step prune --min-age=2d # skip worktrees younger than 2 days
Preview what would be removed:
```bash
-wt step prune --dry-run
+$ wt step prune --dry-run
```
Remove all merged worktrees:
```bash
-wt step prune
+$ wt step prune
```
### Command reference
@@ -733,25 +708,25 @@ Move worktrees to expected paths. Relocates worktrees whose path doesn't match t
Preview what would be moved:
```bash
-wt step relocate --dry-run
+$ wt step relocate --dry-run
```
Move all mismatched worktrees:
```bash
-wt step relocate
+$ wt step relocate
```
Auto-commit and clobber blockers (never fails):
```bash
-wt step relocate --commit --clobber
+$ wt step relocate --commit --clobber
```
Move specific worktrees:
```bash
-wt step relocate feature bugfix
+$ wt step relocate feature bugfix
```
### Swap handling
@@ -831,10 +806,7 @@ port = "echo http://localhost:{{ branch | hash_port }}"
```
```bash
-wt step deploy # run the alias
-wt step deploy --dry-run # show expanded command
-wt step deploy --var env=staging # pass extra template variables
-wt step deploy --yes # skip approval prompt
+$ wt step deploy # run the alias|||wt step deploy --dry-run # show expanded command|||wt step deploy --var env=staging # pass extra template variables|||wt step deploy --yes # skip approval prompt
```
When defined in both user and project config, both run — user first, then project. Project-config aliases require [command approval](https://worktrunk.dev/hook/#wt-hook-approvals) on first run, same as project hooks. User-config aliases are trusted.
diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.md
index 459a04bfb..25d37f635 100644
--- a/skills/worktrunk/reference/switch.md
+++ b/skills/worktrunk/reference/switch.md
@@ -7,11 +7,7 @@ Worktrees are addressed by branch name; paths are computed from a configurable t
## Examples
```bash
-wt switch feature-auth # Switch to worktree
-wt switch - # Previous worktree (like cd -)
-wt switch --create new-feature # Create new branch and worktree
-wt switch --create hotfix --base production
-wt switch pr:123 # Switch to PR #123's branch
+$ wt switch feature-auth # Switch to worktree|||wt switch - # Previous worktree (like cd -)|||wt switch --create new-feature # Create new branch and worktree|||wt switch --create hotfix --base production|||wt switch pr:123 # Switch to PR #123's branch
```
## Creating a branch
@@ -29,10 +25,7 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth
5. Spawns [post-start](https://worktrunk.dev/hook/#post-start) and [post-switch hooks](https://worktrunk.dev/hook/#post-switch) in the background
```bash
-wt switch feature # Existing branch → creates worktree
-wt switch --create feature # New branch and worktree
-wt switch --create fix --base release # New branch from release
-wt switch --create temp --no-verify # Skip hooks
+$ wt switch feature # Existing branch → creates worktree|||wt switch --create feature # New branch and worktree|||wt switch --create fix --base release # New branch from release|||wt switch --create temp --no-verify # Skip hooks
```
## Shortcuts
@@ -46,11 +39,7 @@ wt switch --create temp --no-verify # Skip hooks
| `mr:{N}` | GitLab MR !N's branch |
```bash
-wt switch - # Back to previous
-wt switch ^ # Default branch worktree
-wt switch --create fix --base=@ # Branch from current HEAD
-wt switch pr:123 # PR #123's branch
-wt switch mr:101 # MR !101's branch
+$ wt switch - # Back to previous|||wt switch ^ # Default branch worktree|||wt switch --create fix --base=@ # Branch from current HEAD|||wt switch pr:123 # PR #123's branch|||wt switch mr:101 # MR !101's branch
```
## Interactive picker
@@ -92,8 +81,7 @@ Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch <
The `pr:<number>` and `mr:<number>` shortcuts resolve a GitHub PR or GitLab MR to its branch. For same-repo PRs/MRs, worktrunk switches to the branch directly. For fork PRs/MRs, it fetches the ref (`refs/pull/N/head` or `refs/merge-requests/N/head`) and configures `pushRemote` to the fork URL.
```bash
-wt switch pr:101 # GitHub PR #101
-wt switch mr:101 # GitLab MR !101
+$ wt switch pr:101 # GitHub PR #101|||wt switch mr:101 # GitLab MR !101
```
Requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated. The `--create` flag cannot be used with `pr:`/`mr:` syntax since the branch already exists.
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index f0152b043..98e521389 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -7,9 +7,7 @@ Practical recipes for common Worktrunk workflows.
Create a worktree and launch Claude in one command:
```bash
-alias wsc='wt switch --create --execute=claude'
-wsc new-feature # Creates worktree, runs hooks, launches Claude
-wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`
+$ alias wsc='wt switch --create --execute=claude'|||wsc new-feature # Creates worktree, runs hooks, launches Claude|||wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`
```
## Eliminate cold starts
@@ -43,7 +41,6 @@ server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/nu
The URL column in `wt list` shows each worktree's dev server:
-{% terminal(cmd="wt list") %}
<span class="cmd">wt list</span>
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>URL</b> <b>Commit</b> <b>Age</b>
@ main <span class=c>?</span> <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=d>http://localhost:12107</span> <span class=d>41ee0834</span> <span class=d>4d</span>
@@ -52,7 +49,6 @@ The URL column in `wt list` shows each worktree's dev server:
+ <span class=d>fix-typos</span> <span class=d>_</span><span class=d>|</span> <span class=d>|</span> <span class=d>http://localhost:14301</span> <span class=d>41ee0834</span> <span class=d>4d</span>
<span class=d>○</span> <span class=d>Showing 4 worktrees, 2 with changes, 2 ahead, 2 columns hidden</span>
-{% end %}
Ports are deterministic — `fix-auth` always gets port 16460, regardless of which machine or when. The URL dims if the server isn't running.
@@ -141,9 +137,7 @@ Custom emoji markers show agent state in `wt list`. The Claude Code plugin sets
Set status manually for any workflow:
```bash
-wt config state marker set "🚧" # Current branch
-wt config state marker set "✅" --branch feature # Specific branch
-git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct
+$ wt config state marker set &quot;🚧&quot; # Current branch|||wt config state marker set &quot;✅&quot; --branch feature # Specific branch|||git config worktrunk.state.feature.marker '{&quot;marker&quot;:&quot;💬&quot;,&quot;set_at&quot;:0}' # Direct
```
See [Claude Code Integration](https://worktrunk.dev/claude-code/#installation) for plugin installation.
@@ -151,7 +145,7 @@ See [Claude Code Integration](https://worktrunk.dev/claude-code/#installation) f
## Monitor CI across branches
```bash
-wt list --full --branches
+$ wt list --full --branches
```
Shows PR/CI status for all branches, including those without worktrees. CI indicators are clickable links to the PR page.
@@ -171,7 +165,7 @@ Summaries are cached and regenerated only when the diff changes. See [LLM Commit
## JSON API
```bash
-wt list --format=json
+$ wt list --format=json
```
Structured output for dashboards, statuslines, and scripts. See [`wt list`](https://worktrunk.dev/list/) for query examples.
@@ -181,7 +175,7 @@ Structured output for dashboards, statuslines, and scripts. See [`wt list`](http
Worktrunk maintains useful state. Default branch [detection](https://worktrunk.dev/config/#wt-config-state-default-branch), for instance, means scripts work on any repo — no need to hardcode `main` or `master`:
```bash
-git rebase $(wt config state default-branch)
+$ git rebase $(wt config state default-branch)
```
## Task runners in hooks
@@ -201,9 +195,7 @@ Reference Taskfile/Justfile/Makefile in hooks:
Special arguments work across all commands—see [`wt switch`](https://worktrunk.dev/switch/#shortcuts) for the full list.
```bash
-wt switch --create hotfix --base=@ # Branch from current HEAD
-wt switch - # Switch to previous worktree
-wt remove @ # Remove current worktree
+$ wt switch --create hotfix --base=@ # Branch from current HEAD|||wt switch - # Switch to previous worktree|||wt remove @ # Remove current worktree
```
## Stacked branches
@@ -211,7 +203,7 @@ wt remove @ # Remove current worktree
Branch from current HEAD instead of the default branch:
```bash
-wt switch --create feature-part2 --base=@
+$ wt switch --create feature-part2 --base=@
```
Creates a worktree that builds on the current branch's changes.
@@ -222,14 +214,12 @@ Spawn a worktree with Claude running in the background:
**tmux** (new detached session):
```bash
-tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
- 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"
+$ tmux new-session -d -s fix-auth-bug &quot;wt switch --create fix-auth-bug -x claude -- \||| 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'&quot;
```
**Zellij** (new pane in current session):
```bash
-zellij run -- wt switch --create fix-auth-bug -x claude -- \
- 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'
+$ zellij run -- wt switch --create fix-auth-bug -x claude -- \||| 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'
```
This lets one Claude session hand off work to another that runs in the background. Hooks run inside the multiplexer session/pane.
@@ -275,9 +265,7 @@ tmux = "tmux kill-session -t {{ branch | sanitize }} 2>/dev/null || true"
To create a worktree and immediately attach:
-```bash
-wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'
-```
+<span class="cmd">wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'</span>
## Xcode DerivedData cleanup
@@ -339,7 +327,7 @@ url = "http://{{ branch | sanitize }}.{{ repo }}.localhost:8080"
Follow background hook output in real-time:
```bash
-tail -f "$(wt config state logs get --hook=user:post-start:server)"
+$ tail -f &quot;$(wt config state logs get --hook=user:post-start:server)&quot;
```
The `--hook` format is `source:hook-type:name` — e.g., `project:post-start:build` for project-defined hooks. Use `wt config state logs get` to list all available logs.
@@ -347,7 +335,7 @@ The `--hook` format is `source:hook-type:name` — e.g., `project:post-start:bui
Create an alias for frequent use:
```bash
-alias wtlog='f() { tail -f "$(wt config state logs get --hook="$1")"; }; f'
+$ alias wtlog='f() { tail -f &quot;$(wt config state logs get --hook=&quot;$1&quot;)&quot;; }; f'
```
## Bare repository layout
@@ -357,8 +345,7 @@ A [bare repository](https://git-scm.com/docs/gitrepository-layout) has no workin
Cloning a bare repo into `<project>/.git` puts all worktrees under one directory:
```bash
-git clone --bare <url> myproject/.git
-cd myproject
+$ git clone --bare <url> myproject/.git|||cd myproject
```
With `worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"`, worktrees become subdirectories of `myproject/`:
@@ -381,7 +368,7 @@ worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"
Create the first worktree:
```bash
-wt switch --create main
+$ wt switch --create main
```
Now `wt switch --create feature` creates `myproject/feature/`.
diff --git a/skills/worktrunk/reference/troubleshooting.md b/skills/worktrunk/reference/troubleshooting.md
index ea991a3c4..067ed10a7 100644
--- a/skills/worktrunk/reference/troubleshooting.md
+++ b/skills/worktrunk/reference/troubleshooting.md
@@ -9,8 +9,8 @@ Claude-specific troubleshooting guidance for common worktrunk issues.
Check if the configured tool is installed:
```bash
-$ wt config show # shows the configured command
-$ which claude # or: which codex, which llm, which aichat
+wt config show # shows the configured command
+which claude # or: which codex, which llm, which aichat
```
If empty, install one of the supported tools. See [LLM commits docs](https://worktrunk.dev/llm-commits/) for setup instructions.
@@ -20,7 +20,7 @@ If empty, install one of the supported tools. See [LLM commits docs](https://wor
Test the configured command directly by piping a prompt to it. See `reference/llm-commits.md` for the exact command syntax for each tool.
```bash
-$ echo "say hello" | <your-configured-command>
+echo "say hello" | <your-configured-command>
```
Common issues:
diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.md
index 8eb8f5f03..497ea3f05 100644
--- a/skills/worktrunk/reference/worktrunk.md
+++ b/skills/worktrunk/reference/worktrunk.md
@@ -85,7 +85,7 @@ A demo with some advanced features:
**Homebrew (macOS & Linux):**
```bash
-brew install worktrunk && wt config shell install
+$ brew install worktrunk && wt config shell install
```
Shell integration allows commands to change directories.
@@ -93,7 +93,7 @@ Shell integration allows commands to change directories.
**Cargo:**
```bash
-cargo install worktrunk && wt config shell install
+$ cargo install worktrunk && wt config shell install
```
<details>
@@ -102,8 +102,7 @@ cargo install worktrunk && wt config shell install
On Windows, `wt` defaults to Windows Terminal's command. Winget additionally installs Worktrunk as `git-wt` to avoid the conflict:
```bash
-winget install max-sixty.worktrunk
-git-wt config shell install
+$ winget install max-sixty.worktrunk|||git-wt config shell install
```
Alternatively, disable Windows Terminal's alias (Settings → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal") to use `wt` directly.
@@ -113,28 +112,24 @@ Alternatively, disable Windows Terminal's alias (Settings → Privacy & security
**Arch Linux:**
```bash
-paru worktrunk-bin && wt config shell install
+$ paru worktrunk-bin && wt config shell install
```
## Quick start
Create a worktree for a new feature:
-{% terminal(cmd="wt switch --create feature-auth") %}
<span class="cmd">wt switch --create feature-auth</span>
<span class=g>✓</span> <span class=g>Created branch <b>feature-auth</b> from <b>main</b> and worktree @ <b>repo.feature-auth</b></span>
-{% end %}
This creates a new branch and worktree, then switches to it. Do your work, then check all worktrees with [`wt list`](https://worktrunk.dev/list/):
-{% terminal(cmd="wt list") %}
<span class="cmd">wt list</span>
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>
@ feature-auth <span class=c>+</span> <span class=d>↑</span> <span class=g>+27</span> <span class=r>-8</span> <span class=g>↑1</span> <span class=d>4bc72dc9</span> <span class=d>2h</span> <span class=d>Add authentication module</span>
^ main <span class=d>^</span><span class=d>⇡</span> <span class=g>⇡1</span> <span class=d>0e631add</span> <span class=d>1d</span> <span class=d>Initial commit</span>
<span class=d>○</span> <span class=d>Showing 2 worktrees, 1 with changes, 1 ahead, 1 column hidden</span>
-{% end %}
The `@` marks the current worktree. `+` means staged changes, `↑1` means 1 commit ahead of main, `⇡` means unpushed commits.
@@ -143,14 +138,11 @@ When done, either:
**PR workflow** — commit, push, open a PR, merge via GitHub/GitLab, then clean up:
```bash
-wt step commit # commit staged changes
-gh pr create # or glab mr create
-wt remove # after PR is merged
+$ wt step commit # commit staged changes|||gh pr create # or glab mr create|||wt remove # after PR is merged
```
**Local merge** — squash, rebase onto main, fast-forward merge, clean up:
-{% terminal(cmd="wt merge main") %}
<span class="cmd">wt merge main</span>
<span class=c>◎</span> <span class=c>Generating commit message and committing changes... <span style='color:var(--bright-black,#555)'>(2 files, <span class=g>+53</span></span></span>, no squashing needed<span style='color:var(--bright-black,#555)'>)</span>
<span style='background:var(--bright-white,#fff)'> </span> <b>Add authentication module</b>
@@ -163,14 +155,11 @@ wt remove # after PR is merged
<span class=g>✓</span> <span class=g>Merged to <b>main</b> <span style='color:var(--bright-black,#555)'>(1 commit, 2 files, +53</span></span><span style='color:var(--bright-black,#555)'>)</span>
<span class=c>◎</span> <span class=c>Removing <b>feature-auth</b> worktree &amp; branch in background (same commit as <b>main</b>,</span> <span class=d>_</span><span class=c>)</span>
<span class=d>○</span> Switched to worktree for <b>main</b> @ <b>repo</b>
-{% end %}
For parallel agents, create multiple worktrees and launch an agent in each:
```bash
-wt switch -x claude -c feature-a -- 'Add user authentication'
-wt switch -x claude -c feature-b -- 'Fix the pagination bug'
-wt switch -x claude -c feature-c -- 'Write tests for the API'
+$ wt switch -x claude -c feature-a -- 'Add user authentication'|||wt switch -x claude -c feature-b -- 'Fix the pagination bug'|||wt switch -x claude -c feature-c -- 'Write tests for the API'
```
The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](https://worktrunk.dev/hook/) to automate setup (install deps, start dev servers).
diff --git a/src/cli/config.rs b/src/cli/config.rs
index c6eb478f6..031aa2b72 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -14,7 +14,7 @@ Add one line to the shell config:
Bash (~/.bashrc):
```console
-eval "$(wt config shell init bash)"
+$ eval "$(wt config shell init bash)"
```
Fish (~/.config/fish/config.fish):
@@ -29,7 +29,7 @@ eval "$(wt config shell init zsh)"
Nushell [experimental] — save to vendor autoload directory:
```console
-wt config shell init nu | save -f ($nu.default-config-dir | path join vendor/autoload/wt.nu)
+$ wt config shell init nu | save -f ($nu.default-config-dir | path join vendor/autoload/wt.nu)
```"#
)]
Init {
@@ -54,12 +54,12 @@ wt config shell init nu | save -f ($nu.default-config-dir | path join vendor/aut
Install for all detected shells:
```console
-wt config shell install
+$ wt config shell install
```
Install for specific shell only:
```console
-wt config shell install zsh
+$ wt config shell install zsh
```
Shows proposed changes and waits for confirmation before modifying any files.
@@ -95,17 +95,17 @@ Use --yes to skip confirmation."#
Uninstall from all shells:
```console
-wt config shell uninstall
+$ wt config shell uninstall
```
Uninstall from specific shell only:
```console
-wt config shell uninstall zsh
+$ wt config shell uninstall zsh
```
Skip confirmation prompt:
```console
-wt config shell uninstall --yes
+$ wt config shell uninstall --yes
```
## Version tolerance
@@ -223,7 +223,7 @@ If a config file doesn't exist, shows defaults that would be used.
Use `--full` to run diagnostic checks:
```console
-wt config show --full
+$ wt config show --full
```
This tests:
@@ -246,12 +246,12 @@ to their current equivalents. Shows a diff and asks for confirmation.
Preview and apply updates:
```console
-wt config update
+$ wt config update
```
Apply without confirmation:
```console
-wt config update --yes
+$ wt config update --yes
```"#
)]
Update {
@@ -277,32 +277,32 @@ Use `wt config show` to view file-based configuration.
Get the default branch:
```console
-wt config state default-branch
+$ wt config state default-branch
```
Set the default branch manually:
```console
-wt config state default-branch set main
+$ wt config state default-branch set main
```
Set a marker for current branch:
```console
-wt config state marker set "🚧 WIP"
+$ wt config state marker set "🚧 WIP"
```
Clear all CI status cache:
```console
-wt config state ci-status clear --all
+$ wt config state ci-status clear --all
```
Show all stored state:
```console
-wt config state get
+$ wt config state get
```
Clear all stored state:
```console
-wt config state clear
+$ wt config state clear
```
<!-- subdoc: default-branch -->
<!-- subdoc: ci-status -->
@@ -423,7 +423,7 @@ bugfix 🤖!↑⇡ ~/code/myproject.bugfix
Stored in git config as `worktrunk.state.<branch>.marker`. Set directly with:
```console
-git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
+$ git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
```
Without a subcommand, runs `get` for the current branch. For `--branch`, use `get --branch=NAME`."#
@@ -467,22 +467,22 @@ All logs are stored in `.git/wt/logs/` (in the main worktree's git directory).
List all log files:
```console
-wt config state logs get
+$ wt config state logs get
```
Query the command log:
```console
-tail -5 .git/wt/logs/commands.jsonl | jq .
+$ tail -5 .git/wt/logs/commands.jsonl | jq .
```
View a specific hook log:
```console
-cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"
+$ cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"
```
Clear all logs:
```console
-wt config state logs clear
+$ wt config state logs clear
```"#)]
Logs {
#[command(subcommand)]
@@ -503,9 +503,9 @@ as `worktrunk.hints.<name> = true`.
## Examples
```console
-wt config state hints # list shown hints
-wt config state hints clear # re-show all hints
-wt config state hints clear NAME # re-show specific hint
+$ wt config state hints # list shown hints
+$ wt config state hints clear # re-show all hints
+$ wt config state hints clear NAME # re-show specific hint
```"#
)]
Hints {
@@ -552,12 +552,12 @@ pub enum DefaultBranchAction {
Get the default branch:
```console
-wt config state default-branch
+$ wt config state default-branch
```
Clear cache and re-detect:
```console
-wt config state default-branch clear && wt config state default-branch get
+$ wt config state default-branch clear && wt config state default-branch get
```"#)]
Get,
@@ -566,7 +566,7 @@ wt config state default-branch clear && wt config state default-branch get
Set the default branch:
```console
-wt config state default-branch set main
+$ wt config state default-branch set main
```"#)]
Set {
/// Branch name to set as default
@@ -585,7 +585,7 @@ pub enum PreviousBranchAction {
Get the previous branch (used by `wt switch -`):
```console
-wt config state previous-branch
+$ wt config state previous-branch
```"#)]
Get,
@@ -594,7 +594,7 @@ wt config state previous-branch
Set the previous branch:
```console
-wt config state previous-branch set feature
+$ wt config state previous-branch set feature
```"#)]
Set {
/// Branch name to set as previous
@@ -616,17 +616,17 @@ pub enum CiStatusAction {
Get CI status for current branch:
```console
-wt config state ci-status
+$ wt config state ci-status
```
Get CI status for a specific branch:
```console
-wt config state ci-status get --branch=feature
+$ wt config state ci-status get --branch=feature
```
Clear cache and re-fetch:
```console
-wt config state ci-status clear && wt config state ci-status get
+$ wt config state ci-status clear && wt config state ci-status get
```"#
)]
Get {
@@ -640,17 +640,17 @@ wt config state ci-status clear && wt config state ci-status get
Clear CI status for current branch:
```console
-wt config state ci-status clear
+$ wt config state ci-status clear
```
Clear CI status for a specific branch:
```console
-wt config state ci-status clear --branch=feature
+$ wt config state ci-status clear --branch=feature
```
Clear all CI status cache:
```console
-wt config state ci-status clear --all
+$ wt config state ci-status clear --all
```"#)]
Clear {
/// Target branch (defaults to current)
@@ -670,12 +670,12 @@ pub enum MarkerAction {
Get marker for current branch:
```console
-wt config state marker
+$ wt config state marker
```
Get marker for a specific branch:
```console
-wt config state marker get --branch=feature
+$ wt config state marker get --branch=feature
```"#)]
Get {
/// Target branch (defaults to current)
@@ -688,12 +688,12 @@ wt config state marker get --branch=feature
Set marker for current branch:
```console
-wt config state marker set "🚧 WIP"
+$ wt config state marker set "🚧 WIP"
```
Set marker for a specific branch:
```console
-wt config state marker set "✅ ready" --branch=feature
+$ wt config state marker set "✅ ready" --branch=feature
```"#)]
Set {
/// Marker text (shown in `wt list` output)
@@ -709,17 +709,17 @@ wt config state marker set "✅ ready" --branch=feature
Clear marker for current branch:
```console
-wt config state marker clear
+$ wt config state marker clear
```
Clear marker for a specific branch:
```console
-wt config state marker clear --branch=feature
+$ wt config state marker clear --branch=feature
```
Clear all markers:
```console
-wt config state marker clear --all
+$ wt config state marker clear --all
```"#)]
Clear {
/// Target branch (defaults to current)
@@ -742,27 +742,27 @@ pub enum LogsAction {
List all log files:
```console
-wt config state logs
+$ wt config state logs
```
Get path to a specific hook log:
```console
-wt config state logs get --hook=user:post-start:server
+$ wt config state logs get --hook=user:post-start:server
```
Stream a hook's log output:
```console
-tail -f "$(wt config state logs get --hook=user:post-start:server)"
+$ tail -f "$(wt config state logs get --hook=user:post-start:server)"
```
Get log for background worktree removal:
```console
-wt config state logs get --hook=internal:remove
+$ wt config state logs get --hook=internal:remove
```
Get log for a different branch:
```console
-wt config state logs get --hook=user:post-start:server --branch=feature
+$ wt config state logs get --hook=user:post-start:server --branch=feature
```"#
)]
Get {
@@ -793,7 +793,7 @@ pub enum HintsAction {
List shown hints:
```console
-wt config state hints
+$ wt config state hints
```"#
)]
Get,
@@ -806,12 +806,12 @@ wt config state hints
Clear all hints:
```console
-wt config state hints clear
+$ wt config state hints clear
```
Clear a specific hint:
```console
-wt config state hints clear worktree-path
+$ wt config state hints clear worktree-path
```"#
)]
Clear {
diff --git a/src/cli/hook.rs b/src/cli/hook.rs
index 7621f61e5..136f3c9fd 100644
--- a/src/cli/hook.rs
+++ b/src/cli/hook.rs
@@ -281,17 +281,17 @@ pub enum HookCommand {
Pre-approve all commands for current project:
```console
-wt hook approvals add
+$ wt hook approvals add
```
Clear approvals for current project:
```console
-wt hook approvals clear
+$ wt hook approvals clear
```
Clear global approvals:
```console
-wt hook approvals clear --global
+$ wt hook approvals clear --global
```
## How approvals work
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index beb6928ef..9bacf6d1f 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -255,11 +255,11 @@ pub(crate) enum Commands {
## Examples
```console
-wt switch feature-auth # Switch to worktree
-wt switch - # Previous worktree (like cd -)
-wt switch --create new-feature # Create new branch and worktree
-wt switch --create hotfix --base production
-wt switch pr:123 # Switch to PR #123's branch
+$ wt switch feature-auth # Switch to worktree
+$ wt switch - # Previous worktree (like cd -)
+$ wt switch --create new-feature # Create new branch and worktree
+$ wt switch --create hotfix --base production
+$ wt switch pr:123 # Switch to PR #123's branch
```
## Creating a branch
@@ -277,10 +277,10 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth
5. Spawns [post-start](@/hook.md#post-start) and [post-switch hooks](@/hook.md#post-switch) in the background
```console
-wt switch feature # Existing branch → creates worktree
-wt switch --create feature # New branch and worktree
-wt switch --create fix --base release # New branch from release
-wt switch --create temp --no-verify # Skip hooks
+$ wt switch feature # Existing branch → creates worktree
+$ wt switch --create feature # New branch and worktree
+$ wt switch --create fix --base release # New branch from release
+$ wt switch --create temp --no-verify # Skip hooks
```
## Shortcuts
@@ -294,11 +294,11 @@ wt switch --create temp --no-verify # Skip hooks
| `mr:{N}` | GitLab MR !N's branch |
```console
-wt switch - # Back to previous
-wt switch ^ # Default branch worktree
-wt switch --create fix --base=@ # Branch from current HEAD
-wt switch pr:123 # PR #123's branch
-wt switch mr:101 # MR !101's branch
+$ wt switch - # Back to previous
+$ wt switch ^ # Default branch worktree
+$ wt switch --create fix --base=@ # Branch from current HEAD
+$ wt switch pr:123 # PR #123's branch
+$ wt switch mr:101 # MR !101's branch
```
## Interactive picker
@@ -341,8 +341,8 @@ Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch <
The `pr:<number>` and `mr:<number>` shortcuts resolve a GitHub PR or GitLab MR to its branch. For same-repo PRs/MRs, worktrunk switches to the branch directly. For fork PRs/MRs, it fetches the ref (`refs/pull/N/head` or `refs/merge-requests/N/head`) and configures `pushRemote` to the fork URL.
```console
-wt switch pr:101 # GitHub PR #101
-wt switch mr:101 # GitLab MR !101
+$ wt switch pr:101 # GitHub PR #101
+$ wt switch mr:101 # GitLab MR !101
```
Requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated. The `--create` flag cannot be used with `pr:`/`mr:` syntax since the branch already exists.
@@ -581,28 +581,28 @@ Query structured data with `--format=json`:
```console
# Current worktree path (for scripts)
-wt list --format=json | jq -r '.[] | select(.is_current) | .path'
+$ wt list --format=json | jq -r '.[] | select(.is_current) | .path'
# Branches with uncommitted changes
-wt list --format=json | jq '.[] | select(.working_tree.modified)'
+$ wt list --format=json | jq '.[] | select(.working_tree.modified)'
# Worktrees with merge conflicts
-wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
+$ wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
# Branches ahead of main (needs merging)
-wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
+$ wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
# Integrated branches (safe to remove)
-wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
+$ wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
# Branches without worktrees
-wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
+$ wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
# Worktrees ahead of remote (needs pushing)
-wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
+$ wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
# Stale CI (local changes not reflected in CI)
-wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
+$ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
```
**Fields:**
@@ -751,26 +751,26 @@ Missing a field that would be generally useful? Open an issue at https://github.
Remove current worktree:
```console
-wt remove
+$ wt remove
```
Remove specific worktrees / branches:
```console
-wt remove feature-branch
-wt remove old-feature another-branch
+$ wt remove feature-branch
+$ wt remove old-feature another-branch
```
Keep the branch:
```console
-wt remove --no-delete-branch feature-branch
+$ wt remove --no-delete-branch feature-branch
```
Force-delete an unmerged branch:
```console
-wt remove -D experimental
+$ wt remove -D experimental
```
## Branch cleanup
@@ -799,9 +799,9 @@ Worktrunk has two force flags for different situations:
| `--force-delete` (`-D`) | Branch | Branch has unmerged commits |
```console
-wt remove feature --force # Remove worktree with untracked files
-wt remove feature -D # Delete unmerged branch
-wt remove feature --force -D # Both
+$ wt remove feature --force # Remove worktree with untracked files
+$ wt remove feature -D # Delete unmerged branch
+$ wt remove feature --force -D # Both
```
Without `--force`, removal fails if the worktree contains untracked files. Without `--force-delete`, removal keeps branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of merge status.
@@ -868,37 +868,37 @@ Detached worktrees have no branch name. Pass the worktree path instead: `wt remo
Merge to the default branch:
```console
-wt merge
+$ wt merge
```
Merge to a different branch:
```console
-wt merge develop
+$ wt merge develop
```
Keep the worktree after merging:
```console
-wt merge --no-remove
+$ wt merge --no-remove
```
Preserve commit history (no squash):
```console
-wt merge --no-squash
+$ wt merge --no-squash
```
Create a merge commit — semi-linear history:
```console
-wt merge --no-ff
+$ wt merge --no-ff
```
Skip committing/squashing (rebase still runs unless --no-rebase):
```console
-wt merge --no-commit
+$ wt merge --no-commit
```
## Pipeline
@@ -1028,16 +1028,16 @@ lint = "cargo clippy"
Commit with LLM-generated message:
```console
-wt step commit
+$ wt step commit
```
Manual merge workflow with review between steps:
```console
-wt step commit
-wt step squash
-wt step rebase
-wt step push
+$ wt step commit
+$ wt step squash
+$ wt step rebase
+$ wt step push
```
## Operations
@@ -1081,10 +1081,10 @@ port = "echo http://localhost:{{ branch | hash_port }}"
```
```console
-wt step deploy # run the alias
-wt step deploy --dry-run # show expanded command
-wt step deploy --var env=staging # pass extra template variables
-wt step deploy --yes # skip approval prompt
+$ wt step deploy # run the alias
+$ wt step deploy --dry-run # show expanded command
+$ wt step deploy --var env=staging # pass extra template variables
+$ wt step deploy --yes # skip approval prompt
```
When defined in both user and project config, both run — user first, then project. Project-config aliases require [command approval](@/hook.md#wt-hook-approvals) on first run, same as project hooks. User-config aliases are trusted.
@@ -1375,14 +1375,14 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:
`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.
```console
-wt hook pre-merge # Run all pre-merge hooks
-wt hook pre-merge test # Run hooks named "test" from both sources
-wt hook pre-merge user: # Run all user hooks
-wt hook pre-merge project: # Run all project hooks
-wt hook pre-merge user:test # Run only user's "test" hook
-wt hook pre-merge project:test # Run only project's "test" hook
-wt hook pre-merge --yes # Skip approval prompts (for CI)
-wt hook pre-start --var branch=feature/test # Override template variable
+$ wt hook pre-merge # Run all pre-merge hooks
+$ wt hook pre-merge test # Run hooks named "test" from both sources
+$ wt hook pre-merge user: # Run all user hooks
+$ wt hook pre-merge project: # Run all project hooks
+$ wt hook pre-merge user:test # Run only user's "test" hook
+$ wt hook pre-merge project:test # Run only project's "test" hook
+$ wt hook pre-merge --yes # Skip approval prompts (for CI)
+$ wt hook pre-start --var branch=feature/test # Override template variable
```
The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.
@@ -1602,25 +1602,25 @@ For copying dependencies and caches between worktrees, see [`wt step copy-ignore
Install shell integration (required for directory switching):
```console
-wt config shell install
+$ wt config shell install
```
Create user config file with documented examples:
```console
-wt config create
+$ wt config create
```
Create project config file (`.config/wt.toml`) for hooks:
```console
-wt config create --project
+$ wt config create --project
```
Show current configuration and file locations:
```console
-wt config show
+$ wt config show
```
## Configuration files
@@ -1968,7 +1968,7 @@ test = "cargo test"
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
```console
-wt config shell install
+$ wt config shell install
```
For manual setup, see `wt config shell init --help`.
@@ -2004,7 +2004,7 @@ Note the single underscore after `WORKTRUNK` and double underscores between nest
Override the LLM command in CI to use a mock:
```console
-WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
+$ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
```
### Other environment variables
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 2a59ad482..1f37c7c7c 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -21,7 +21,7 @@ Controls what to stage before committing:
| `none` | Don't stage anything, commit only what's already staged |
```console
-wt step commit --stage=tracked
+$ wt step commit --stage=tracked
```
Configure the default in user config:
@@ -37,10 +37,10 @@ Output the rendered LLM prompt to stdout without running the command. Useful for
```console
# Inspect the rendered prompt
-wt step commit --show-prompt | less
+$ wt step commit --show-prompt | less
# Pipe to a different LLM
-wt step commit --show-prompt | llm -m gpt-5-nano
+$ wt step commit --show-prompt | llm -m gpt-5-nano
```
"#
)]
@@ -83,7 +83,7 @@ Controls what to stage before squashing:
| `none` | Don't stage anything, squash only committed changes |
```console
-wt step squash --stage=none
+$ wt step squash --stage=none
```
Configure the default in user config:
@@ -98,7 +98,7 @@ stage = "tracked"
Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
```console
-wt step squash --show-prompt | less
+$ wt step squash --show-prompt | less
```
"#
)]
@@ -135,8 +135,8 @@ wt step squash --show-prompt | less
## Examples
```console
-wt step push # Fast-forward main to current branch
-wt step push develop # Fast-forward develop instead
+$ wt step push # Fast-forward main to current branch
+$ wt step push develop # Fast-forward develop instead
```
Similar to `git push . HEAD:<target>`, but uses `receive.denyCurrentBranch=updateInstead` internally.
@@ -165,8 +165,8 @@ Similar to `git push . HEAD:<target>`, but uses `receive.denyCurrentBranch=updat
## Examples
```console
-wt step rebase # Rebase onto default branch
-wt step rebase develop # Rebase onto develop
+$ wt step rebase # Rebase onto default branch
+$ wt step rebase develop # Rebase onto develop
```
"#
)]
@@ -189,15 +189,15 @@ wt step rebase develop # Rebase onto develop
Arguments after `--` are forwarded to `git diff`:
```console
-wt step diff -- --stat
-wt step diff -- --name-only
-wt step diff -- -- '*.rs'
+$ wt step diff -- --stat
+$ wt step diff -- --name-only
+$ wt step diff -- -- '*.rs'
```
The diff is pipeable to tools like `delta`:
```console
-wt step diff | delta
+$ wt step diff | delta
```
## How it works
@@ -205,9 +205,9 @@ wt step diff | delta
Equivalent to:
```console
-cp "$(git rev-parse --git-dir)/index" /tmp/idx
-GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .
-GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))
+$ cp "$(git rev-parse --git-dir)/index" /tmp/idx
+$ GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .
+$ GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))
```
`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.
@@ -409,25 +409,25 @@ All variables are shell-escaped. See [`wt hook` template variables](@/hook.md#te
Check status across all worktrees:
```console
-wt step for-each -- git status --short
+$ wt step for-each -- git status --short
```
Run npm install in all worktrees:
```console
-wt step for-each -- npm install
+$ wt step for-each -- npm install
```
Use branch name in command:
```console
-wt step for-each -- "echo Branch: {{ branch }}"
+$ wt step for-each -- "echo Branch: {{ branch }}"
```
Pull updates in worktrees with upstreams (skips others):
```console
-git fetch --prune && wt step for-each -- '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'
+$ 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.
@@ -505,8 +505,8 @@ Locked worktrees and the main worktree are always skipped. The current worktree
Worktrees younger than `--min-age` (default: 1 hour) are skipped. This prevents removing a worktree just created from the default branch — it looks "merged" because its branch points at the same commit.
```console
-wt step prune --min-age=0s # no age guard
-wt step prune --min-age=2d # skip worktrees younger than 2 days
+$ wt step prune --min-age=0s # no age guard
+$ wt step prune --min-age=2d # skip worktrees younger than 2 days
```
## Examples
@@ -514,13 +514,13 @@ wt step prune --min-age=2d # skip worktrees younger than 2 days
Preview what would be removed:
```console
-wt step prune --dry-run
+$ wt step prune --dry-run
```
Remove all merged worktrees:
```console
-wt step prune
+$ wt step prune
```
"#
)]
@@ -550,25 +550,25 @@ wt step prune
Preview what would be moved:
```console
-wt step relocate --dry-run
+$ wt step relocate --dry-run
```
Move all mismatched worktrees:
```console
-wt step relocate
+$ wt step relocate
```
Auto-commit and clobber blockers (never fails):
```console
-wt step relocate --commit --clobber
+$ wt step relocate --commit --clobber
```
Move specific worktrees:
```console
-wt step relocate feature bugfix
+$ wt step relocate feature bugfix
```
## Swap handling
diff --git a/src/docs.rs b/src/docs.rs
new file mode 100644
index 000000000..0ae5baf83
--- /dev/null
+++ b/src/docs.rs
@@ -0,0 +1,186 @@
+//! Documentation text transformations.
+//!
+//! Converts `$ `‐prefixed `console` code blocks into Zola `{% terminal() %}`
+//! shortcodes. Used by both the `--help-page` generator (CLI source → web docs)
+//! and the doc sync test (hand-written docs → web docs).
+
+/// Convert `$ `‐prefixed console blocks into `{% terminal() %}` shortcodes.
+///
+/// All shell commands in `console` blocks use `$ ` prefix. This function detects
+/// them and emits the appropriate shortcode form:
+///
+/// - Single command, no `{{ }}`: `{{ terminal(cmd="...") }}` (Syntect highlighting)
+/// - Single command + output, no `{{ }}`: `{% terminal(cmd="...") %}output{% end %}`
+/// - Multiple commands or `{{ }}`: `{% terminal() %}` with `<span class="cmd">` body
+///
+/// Blocks without `$ ` are left unchanged for the `console` → `bash` replacement.
+pub fn convert_dollar_console_to_terminal(text: &str) -> String {
+ let mut result = String::with_capacity(text.len());
+ let mut lines = text.lines().peekable();
+
+ while let Some(line) = lines.next() {
+ if line.trim_start() == "```console" {
+ // Collect the block, then decide whether to convert
+ let mut block_lines = Vec::new();
+ for content_line in lines.by_ref() {
+ let stripped = content_line.trim_start();
+ if stripped.starts_with("```")
+ && (stripped.len() == 3 || !stripped.as_bytes()[3].is_ascii_alphabetic())
+ {
+ break;
+ }
+ block_lines.push(content_line);
+ }
+
+ // Only convert if the block contains $ commands
+ let commands: Vec<_> = block_lines
+ .iter()
+ .filter_map(|l| l.strip_prefix("$ "))
+ .collect();
+
+ if commands.is_empty() {
+ // No $ lines — emit unchanged as console block
+ result.push_str(line);
+ result.push('\n');
+ for bl in &block_lines {
+ result.push_str(bl);
+ result.push('\n');
+ }
+ result.push_str("```\n");
+ continue;
+ }
+
+ let has_template_syntax = commands.iter().any(|c| c.contains("{{"));
+
+ if has_template_syntax {
+ // {{ }} in commands — must use body approach (Tera would interpret
+ // template syntax in cmd parameter). Accent color only.
+ result.push_str("{% terminal() %}\n");
+ for bl in &block_lines {
+ if let Some(cmd) = bl.strip_prefix("$ ") {
+ result.push_str("<span class=\"cmd\">");
+ for ch in cmd.chars() {
+ match ch {
+ '<' => result.push_str("&lt;"),
+ '>' => result.push_str("&gt;"),
+ '&' => result.push_str("&amp;"),
+ _ => result.push(ch),
+ }
+ }
+ result.push_str("</span>\n");
+ } else {
+ result.push_str(bl);
+ result.push('\n');
+ }
+ }
+ result.push_str("{% end %}\n");
+ } else {
+ // No {{ }} — use cmd parameter for Syntect highlighting.
+ // Multiple commands/comments joined with ||| delimiter;
+ // the template splits and highlights each line individually.
+ let cmd_value: Vec<_> = block_lines
+ .iter()
+ .filter_map(|l| {
+ if let Some(cmd) = l.strip_prefix("$ ") {
+ Some(cmd.replace('"', "&quot;"))
+ } else if l.starts_with('#') || l.is_empty() {
+ Some(l.to_string())
+ } else {
+ None // output lines go in body
+ }
+ })
+ .collect();
+ let body_lines: Vec<_> = block_lines
+ .iter()
+ .filter(|l| !l.starts_with("$ ") && !l.starts_with('#') && !l.is_empty())
+ .collect();
+
+ let cmd_str = cmd_value.join("|||");
+ if body_lines.is_empty() {
+ result.push_str(&format!("{{{{ terminal(cmd=\"{cmd_str}\") }}}}\n"));
+ } else {
+ result.push_str(&format!("{{% terminal(cmd=\"{cmd_str}\") %}}\n"));
+ for bl in &body_lines {
+ result.push_str(bl);
+ result.push('\n');
+ }
+ result.push_str("{% end %}\n");
+ }
+ }
+ continue;
+ }
+ result.push_str(line);
+ result.push('\n');
+ }
+
+ // .lines() strips the trailing newline; match original
+ if !text.ends_with('\n') {
+ result.pop();
+ }
+ result
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use insta::assert_snapshot;
+
+ #[test]
+ fn test_convert_dollar_console_to_terminal() {
+ // Command+output with {{ }} → body approach
+ assert_snapshot!(convert_dollar_console_to_terminal(
+ "```console\n$ wt step eval '{{ branch | hash_port }}'\n16066\n```"
+ ), @r#"
+ {% terminal() %}
+ <span class="cmd">wt step eval '{{ branch | hash_port }}'</span>
+ 16066
+ {% end %}
+ "#);
+
+ // Command only (no $) → unchanged
+ assert_snapshot!(convert_dollar_console_to_terminal(
+ "```console\nwt step commit --stage=tracked\n```"
+ ), @r"
+ ```console
+ wt step commit --stage=tracked
+ ```
+ ");
+
+ // Multi-line output, no {{ }} → cmd parameter
+ assert_snapshot!(convert_dollar_console_to_terminal(
+ "```console\n$ wt step eval --dry-run 'test'\nbranch=feature/auth\nResult: feature/auth\n```"
+ ), @r#"
+ {% terminal(cmd="wt step eval --dry-run 'test'") %}
+ branch=feature/auth
+ Result: feature/auth
+ {% end %}
+ "#);
+
+ // Single command with output, no {{ }} → cmd parameter
+ assert_snapshot!(convert_dollar_console_to_terminal(
+ "```console\n$ echo 'PORT=8080' > .env\noutput\n```"
+ ), @r#"
+ {% terminal(cmd="echo 'PORT=8080' > .env") %}
+ output
+ {% end %}
+ "#);
+
+ // Command only (single, no output) → self-closing shortcode
+ assert_snapshot!(convert_dollar_console_to_terminal(
+ "```console\n$ wt remove\n```"
+ ), @r#"{{ terminal(cmd="wt remove") }}
+ "#);
+
+ // Multiple commands → |||‐delimited cmd with Syntect highlighting
+ assert_snapshot!(convert_dollar_console_to_terminal(
+ "```console\n$ wt step push\n$ wt step push develop\n```"
+ ), @r#"{{ terminal(cmd="wt step push|||wt step push develop") }}
+ "#);
+
+ // Comment before $ commands → included in cmd, Syntect highlights as comment
+ assert_snapshot!(convert_dollar_console_to_terminal(
+ "```console\n# Recent commands\n$ tail -5 log.jsonl | jq .\n\n# Failed\n$ jq 'select(.exit != 0)' log.jsonl\n```"
+ ), @r##"{{ terminal(cmd="# Recent commands|||tail -5 log.jsonl | jq .||||||# Failed|||jq 'select(.exit != 0)' log.jsonl") }}
+ "##);
+ }
+}
diff --git a/src/help.rs b/src/help.rs
index 8d89ab299..22b7a8dcf 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -18,6 +18,10 @@
//! combine_command_docs() — assembles "definition. subtitle\n\n<after_long_help>"
//! │
//! ▼
+//! convert_dollar_console_to_terminal() — ```console with $ → {% terminal() %} shortcode
+//! console→bash replacement — remaining ```console → ```bash
+//! │
+//! ▼
//! post_process_for_html() — text replacements on after_long_help markdown:
//! │ [experimental] → badge <span>
//! │ `●` green → colored <span>
@@ -46,6 +50,7 @@ use std::process;
use ansi_str::AnsiStr;
use clap::ColorChoice;
use clap::error::ErrorKind;
+use worktrunk::docs::convert_dollar_console_to_terminal;
use worktrunk::styling::eprintln;
use crate::cli;
@@ -360,10 +365,11 @@ Commands with pages: merge, switch, remove, list"
};
// Get combined docs: about + subtitle + after_long_help
- // Transform for web docs: console→bash, status colors, demo images
+ // Transform for web docs: $→terminal shortcode, console→bash, status colors, demo images
// Subdocs are expanded separately so main Command reference comes first
let parent_name = format!("wt {}", subcommand);
let raw_help = combine_command_docs(sub);
+ let raw_help = convert_dollar_console_to_terminal(&raw_help);
let raw_help = raw_help.replace("```console\n", "```bash\n");
// Split content at first subdoc placeholder
@@ -652,6 +658,7 @@ fn format_subcommand_section(
// Get combined docs: about + subtitle + after_long_help
let raw_help = combine_command_docs(sub);
+ let raw_help = convert_dollar_console_to_terminal(&raw_help);
let raw_help = raw_help.replace("```console\n", "```bash\n");
// Extract [experimental] marker from content start → badge after heading.
diff --git a/src/lib.rs b/src/lib.rs
index c8919e3c7..aeb641884 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -10,6 +10,7 @@
pub mod command_log;
pub mod config;
pub mod copy;
+pub mod docs;
pub mod git;
pub mod path;
pub mod shell;
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 0aaea4542..52922b563 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -365,11 +365,11 @@ fn update_section(
// =============================================================================
/// Regex to find command placeholder comments in help pages
-/// Matches: <!-- wt <args> -->\n```bash\n$ wt <args>\n```
+/// Matches: <!-- wt <args> -->\n```bash\nwt <args>\n```
/// The HTML comment triggers expansion, the code block shows in terminal help
/// Note: Pattern expects ```bash``` because --help-page converts ```console``` first
static COMMAND_PLACEHOLDER_PATTERN: LazyLock<Regex> =
- LazyLock::new(|| Regex::new(r"<!-- (wt [^>]+) -->\n```bash\n\$ wt [^\n]+\n```").unwrap());
+ LazyLock::new(|| Regex::new(r"<!-- (wt [^>]+) -->\n```bash\nwt [^\n]+\n```").unwrap());
/// Map commands to their snapshot files for help page expansion
fn command_to_snapshot(command: &str) -> Option<&'static str> {
@@ -1567,7 +1567,7 @@ fn sync_command_pages(project_root: &Path) -> (Vec<String>, Vec<String>) {
continue;
}
- // Expand command placeholders ($ wt list -> terminal shortcode with snapshot output)
+ // Expand command placeholders (wt list -> terminal shortcode with snapshot output)
let snapshots_dir = project_root.join("tests/snapshots");
let generated = match expand_command_placeholders(&generated, &snapshots_dir) {
Ok(expanded) => expanded,
@@ -1655,9 +1655,13 @@ static ZOLA_FRONTMATTER_PATTERN: LazyLock<Regex> =
static ZOLA_TITLE_PATTERN: LazyLock<Regex> =
LazyLock::new(|| Regex::new(r#"title\s*=\s*"([^"]+)""#).unwrap());
-/// Regex to strip Zola terminal shortcodes ({% terminal() %}...{% end %})
-static ZOLA_TERMINAL_PATTERN: LazyLock<Regex> =
- LazyLock::new(|| Regex::new(r"(?s)\{% terminal\(\) %\}\n?(.*?)\{% end %\}").unwrap());
+/// Regex to strip body-form terminal shortcodes ({% terminal(...) %}...{% end %})
+static ZOLA_TERMINAL_BODY_PATTERN: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r#"(?s)\{% terminal\([^)]*\) %\}\n?(.*?)\{% end %\}"#).unwrap());
+
+/// Regex to strip self-closing terminal shortcodes ({{ terminal(cmd="...") }})
+static ZOLA_TERMINAL_SELF_CLOSING_PATTERN: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r#"\{\{ terminal\(cmd="([^"]*)"\) \}\}"#).unwrap());
/// Regex to replace Zola experimental shortcode with plain text for skill files
static ZOLA_EXPERIMENTAL_SHORTCODE: LazyLock<Regex> =
@@ -1694,8 +1698,11 @@ fn transform_docs_for_skill(content: &str) -> String {
// Strip frontmatter
let content = ZOLA_FRONTMATTER_PATTERN.replace(content, "");
- // Strip terminal shortcodes, keeping inner content
- let content = ZOLA_TERMINAL_PATTERN.replace_all(&content, "$1");
+ // Strip terminal shortcodes:
+ // - Body form: keep inner content
+ // - Self-closing: convert to `$ command` (plain text with prompt)
+ let content = ZOLA_TERMINAL_BODY_PATTERN.replace_all(&content, "$1");
+ let content = ZOLA_TERMINAL_SELF_CLOSING_PATTERN.replace_all(&content, "```bash\n$$ $1\n```");
// Strip AUTO-GENERATED marker comments (keep content)
let content = AUTO_GENERATED_MARKER_PATTERN.replace_all(&content, "");
@@ -1769,6 +1776,32 @@ fn remove_section(content: &str, heading: &str) -> String {
}
}
+/// Convert ```console blocks with $ to terminal shortcodes in all docs files.
+///
+/// Command pages already have this conversion via --help-page, but hand-written
+/// docs (faq.md, llm-commits.md, claude-code.md) can also use ```console with $
+/// and get the same treatment.
+fn convert_console_blocks_in_docs(project_root: &Path) -> Vec<String> {
+ let docs_dir = project_root.join("docs/content");
+ let mut updated_files = Vec::new();
+
+ for entry in fs::read_dir(&docs_dir).unwrap() {
+ let entry = entry.unwrap();
+ let path = entry.path();
+ if path.extension().is_some_and(|e| e == "md") {
+ let content = fs::read_to_string(&path).unwrap();
+ let converted = worktrunk::docs::convert_dollar_console_to_terminal(&content);
+ if converted != content {
+ fs::write(&path, &converted).unwrap();
+ let rel = path.strip_prefix(project_root).unwrap_or(&path);
+ updated_files.push(rel.display().to_string());
+ }
+ }
+ }
+
+ updated_files
+}
+
/// Sync all docs/content/*.md files to skills/worktrunk/reference/*.md
/// (excluding _index.md which is a Zola template)
/// Returns (errors, updated_files)
@@ -1920,6 +1953,10 @@ fn test_command_pages_and_skill_files_are_in_sync() {
// Step 1: Sync command pages (mod.rs → docs/content/*.md)
let (cmd_errors, cmd_files) = sync_command_pages(project_root);
+ // Step 1b: Convert $ console blocks to terminal shortcodes in ALL docs
+ // (command pages already converted via --help-page; this catches hand-written docs)
+ let console_files = convert_console_blocks_in_docs(project_root);
+
// Step 2: Sync skill files (docs/content/*.md → skills/*)
// This reads the freshly-written docs from step 1
let (skill_errors, skill_files) = sync_skill_files(project_root);
@@ -1932,6 +1969,7 @@ fn test_command_pages_and_skill_files_are_in_sync() {
let all_errors: Vec<_> = cmd_errors.into_iter().chain(skill_errors).collect();
let all_files: Vec<_> = cmd_files
.into_iter()
+ .chain(console_files)
.chain(skill_files)
.chain(well_known_files)
.collect();
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 1ff842376..349a210b7 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -62,19 +62,19 @@ Usage: wt config [OPTIONS] <COMMAND>
Install shell integration (required for directory switching):
-  wt config shell install
+  $ wt config shell install
Create user config file with documented examples:
-  wt config create
+  $ wt config create
Create project config file (.config/wt.toml) for hooks:
-  wt config create --project
+  $ wt config create --project
Show current configuration and file locations:
-  wt config show
+  $ wt config show
Configuration files
@@ -378,7 +378,7 @@ See wt hook for hook types, execution order, template variables, and exa
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
-  wt config shell install
+  $ wt config shell install
For manual setup, see wt config shell init --help.
@@ -412,7 +412,7 @@ Note the single underscore after WORKTRUNK and double underscores betwee
Override the LLM command in CI to use a mock:
-  WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
+  $ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
Other environment variables
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_show.snap b/tests/snapshots/integration__integration_tests__help__help_config_show.snap
index d4ea22806..2dea5869f 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_show.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_show.snap
@@ -62,7 +62,7 @@ If a config file doesn't exist, shows defaults that would be used.
Use --full to run diagnostic checks:
-  wt config show --full
+  $ wt config show --full
This tests:
- CI tool status — Whether gh (GitHub) or glab (GitLab) is installed and authenticated
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state.snap b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
index 534e450a8..d6e95019e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
@@ -74,19 +74,19 @@ Use wt config show to view file-based configuration.
Examples
Get the default branch:
-  wt config state default-branch
+  $ wt config state default-branch
Set the default branch manually:
-  wt config state default-branch set main
+  $ wt config state default-branch set main
Set a marker for current branch:
-  wt config state marker set "🚧 WIP"
+  $ wt config state marker set "🚧 WIP"
Clear all CI status cache:
-  wt config state ci-status clear --all
+  $ wt config state ci-status clear --all
Show all stored state:
-  wt config state get
+  $ wt config state get
Clear all stored state:
-  wt config state clear
+  $ wt config state clear
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap
index 9f169914d..3a31b664a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap
@@ -87,13 +87,13 @@ All logs are stored in .git/wt/logs/ (in the main worktree's git directo
Examples
List all log files:
-  wt config state logs get
+  $ wt config state logs get
Query the command log:
-  tail -5 .git/wt/logs/commands.jsonl | jq .
+  $ tail -5 .git/wt/logs/commands.jsonl | jq .
View a specific hook log:
-  cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"
+  $ cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"
Clear all logs:
-  wt config state logs clear
+  $ wt config state logs clear
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snap
index 84751699e..de0317c85 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snap
@@ -77,6 +77,6 @@ Markers appear at the start of the Status column:
Stored in git config as worktrunk.state.<branch>.marker. Set directly with:
-  git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
+  $ git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
Without a subcommand, runs get for the current branch. For --branch, use get --branch=NAME.
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap b/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
index 908631227..3484168a5 100644
--- a/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
@@ -59,13 +59,13 @@ Project hooks require approval on first run to prevent untrusted projects from r
Examples
Pre-approve all commands for current project:
-  wt hook approvals add
+  $ wt hook approvals add
Clear approvals for current project:
-  wt hook approvals clear
+  $ wt hook approvals clear
Clear global approvals:
-  wt hook approvals clear --global
+  $ wt hook approvals clear --global
How approvals work
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index d0290b64d..d8fae130c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -186,28 +186,28 @@ These appear across all columns while the table is loading:
Query structured data with --format=json:
  # Current worktree path (for scripts)
-  wt list --format=json | jq -r '.[] | select(.is_current) | .path'
+  $ wt list --format=json | jq -r '.[] | select(.is_current) | .path'
  
  # Branches with uncommitted changes
-  wt list --format=json | jq '.[] | select(.working_tree.modified)'
+  $ wt list --format=json | jq '.[] | select(.working_tree.modified)'
  
  # Worktrees with merge conflicts
-  wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
+  $ wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
  
  # Branches ahead of main (needs merging)
-  wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
+  $ wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
  
  # Integrated branches (safe to remove)
-  wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
+  $ wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
  
  # Branches without worktrees
-  wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
+  $ wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
  
  # Worktrees ahead of remote (needs pushing)
-  wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
+  $ wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
  
  # Stale CI (local changes not reflected in CI)
-  wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
+  $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
Fields:
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index d7fb82e84..18cd65903 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
@@ -208,31 +208,31 @@ These appear across all columns while the table is loading:
Query structured data with --format=json:
  # Current worktree path (for scripts)
-  wt list --format=json | jq -r '.[] | select(.is_current) | .path'
+  $ wt list --format=json | jq -r '.[] | select(.is_current) | .path'
  
  # Branches with uncommitted changes
-  wt list --format=json | jq '.[] | select(.working_tree.modified)'
+  $ wt list --format=json | jq '.[] | select(.working_tree.modified)'
  
  # Worktrees with merge conflicts
-  wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
+  $ wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
  
  # Branches ahead of main (needs merging)
-  wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
+  $ wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
  
  # Integrated branches (safe to remove)
-  wt list --format=json | jq '.[] | select(.main_state == "integrated" or 
+  $ wt list --format=json | jq '.[] | select(.main_state == "integrated" or 
  .main_state == "empty") | .branch'
  
  # Branches without worktrees
-  wt list --format=json --branches | jq '.[] | select(.kind == "branch") | 
+  $ wt list --format=json --branches | jq '.[] | select(.kind == "branch") | 
  .branch'
  
  # Worktrees ahead of remote (needs pushing)
-  wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: 
-  .remote.ahead}'
+  $ wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, 
+  ahead: .remote.ahead}'
  
  # Stale CI (local changes not reflected in CI)
-  wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
+  $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
Fields:
diff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
index 655beabbd..38628290e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
@@ -93,37 +93,37 @@ Unlike `git merge`, this merges the current branch into the target branch — no
Merge to the default branch:
```bash
-wt merge
+$ wt merge
```
Merge to a different branch:
```bash
-wt merge develop
+$ wt merge develop
```
Keep the worktree after merging:
```bash
-wt merge --no-remove
+$ wt merge --no-remove
```
Preserve commit history (no squash):
```bash
-wt merge --no-squash
+$ wt merge --no-squash
```
Create a merge commit — semi-linear history:
```bash
-wt merge --no-ff
+$ wt merge --no-ff
```
Skip committing/squashing (rebase still runs unless --no-rebase):
```bash
-wt merge --no-commit
+$ wt merge --no-commit
```
## Pipeline
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
index fbc451805..8a167d087 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -93,27 +93,27 @@ Unlike git merge, this merges the current branch into the target branch
Merge to the default branch:
-  wt merge
+  $ wt merge
Merge to a different branch:
-  wt merge develop
+  $ wt merge develop
Keep the worktree after merging:
-  wt merge --no-remove
+  $ wt merge --no-remove
Preserve commit history (no squash):
-  wt merge --no-squash
+  $ wt merge --no-squash
Create a merge commit — semi-linear history:
-  wt merge --no-ff
+  $ wt merge --no-ff
Skip committing/squashing (rebase still runs unless --no-rebase):
-  wt merge --no-commit
+  $ wt merge --no-commit
Pipeline
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index 74dd8e662..6319dbdaa 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -80,20 +80,20 @@ Usage: wt remove [OPTIONS] [BRANCHES]...
Remove current worktree:
-  wt remove
+  $ wt remove
Remove specific worktrees / branches:
-  wt remove feature-branch
-  wt remove old-feature another-branch
+  $ wt remove feature-branch
+  $ wt remove old-feature another-branch
Keep the branch:
-  wt remove --no-delete-branch feature-branch
+  $ wt remove --no-delete-branch feature-branch
Force-delete an unmerged branch:
-  wt remove -D experimental
+  $ wt remove -D experimental
Branch cleanup
@@ -120,9 +120,9 @@ Worktrunk has two force flags for different situations:
--force (-f) Worktree Worktree has untracked files
--force-delete (-D) Branch Branch has unmerged commits
-  wt remove feature --force # Remove worktree with untracked files
-  wt remove feature -D # Delete unmerged branch
-  wt remove feature --force -D # Both
+  $ wt remove feature --force # Remove worktree with untracked files
+  $ wt remove feature -D # Delete unmerged branch
+  $ wt remove feature --force -D # Both
Without --force, removal fails if the worktree contains untracked files. Without --force-delete, removal keeps branches with unmerged changes. Use --no-delete-branch to keep the branch regardless of merge status.
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index fc171dd88..9857126b7 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -68,14 +68,14 @@ Usage: wt step [OPTIONS] <COMMAND>
Commit with LLM-generated message:
-  wt step commit
+  $ wt step commit
Manual merge workflow with review between steps:
-  wt step commit
-  wt step squash
-  wt step rebase
-  wt step push
+  $ wt step commit
+  $ wt step squash
+  $ wt step rebase
+  $ wt step push
Operations
@@ -106,10 +106,10 @@ Custom command templates configured in user config (~/.config/worktrunk/conf
  deploy = "make deploy BRANCH={{ branch }}"
  port = "echo http://localhost:{{ branch | hash_port }}"
-  wt step deploy # run the alias
-  wt step deploy --dry-run # show expanded command
-  wt step deploy --var env=staging # pass extra template variables
-  wt step deploy --yes # skip approval prompt
+  $ wt step deploy # run the alias
+  $ wt step deploy --dry-run # show expanded command
+  $ wt step deploy --var env=staging # pass extra template variables
+  $ wt step deploy --yes # skip approval prompt
When defined in both user and project config, both run — user first, then project. Project-config aliases require command approval on first run, same as project hooks. User-config aliases are trusted.
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index d7b162269..e1b497c74 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -112,11 +112,11 @@ Worktrees are addressed by branch name; paths are computed from a configurable t
Examples
-  wt switch feature-auth # Switch to worktree
-  wt switch - # Previous worktree (like cd -)
-  wt switch --create new-feature # Create new branch and worktree
-  wt switch --create hotfix --base production
-  wt switch pr:123 # Switch to PR #123's branch
+  $ wt switch feature-auth # Switch to worktree
+  $ wt switch - # Previous worktree (like cd -)
+  $ wt switch --create new-feature # Create new branch and worktree
+  $ wt switch --create hotfix --base production
+  $ wt switch pr:123 # Switch to PR #123's branch
Creating a branch
@@ -132,10 +132,10 @@ If the branch already has a worktree, wt switch changes directories to i
4. Runs pre-start hooks, blocking until complete
5. Spawns post-start and post-switch hooks in the background
-  wt switch feature # Existing branch → creates worktree
-  wt switch --create feature # New branch and worktree
-  wt switch --create fix --base release # New branch from release
-  wt switch --create temp --no-verify # Skip hooks
+  $ wt switch feature # Existing branch → creates worktree
+  $ wt switch --create feature # New branch and worktree
+  $ wt switch --create fix --base release # New branch from release
+  $ wt switch --create temp --no-verify # Skip hooks
Shortcuts
@@ -147,11 +147,11 @@ If the branch already has a worktree, wt switch changes directories to i
pr:{N} GitHub PR #N's branch
mr:{N} GitLab MR !N's branch
-  wt switch - # Back to previous
-  wt switch ^ # Default branch worktree
-  wt switch --create fix --base=@ # Branch from current HEAD
-  wt switch pr:123 # PR #123's branch
-  wt switch mr:101 # MR !101's branch
+  $ wt switch - # Back to previous
+  $ wt switch ^ # Default branch worktree
+  $ wt switch --create fix --base=@ # Branch from current HEAD
+  $ wt switch pr:123 # PR #123's branch
+  $ wt switch mr:101 # MR !101's branch
Interactive picker
@@ -189,8 +189,8 @@ Available on Unix only (macOS, Linux). On Windows, use wt list or wt
The pr:<number> and mr:<number> shortcuts resolve a GitHub PR or GitLab MR to its branch. For same-repo PRs/MRs, worktrunk switches to the branch directly. For fork PRs/MRs, it fetches the ref (refs/pull/N/head or refs/merge-requests/N/head) and configures pushRemote to the fork URL.
-  wt switch pr:101 # GitHub PR #101
-  wt switch mr:101 # GitLab MR !101
+  $ wt switch pr:101 # GitHub PR #101
+  $ wt switch mr:101 # GitLab MR !101
Requires gh (GitHub) or glab (GitLab) CLI to be installed and authenticated. The --create flag cannot be used with pr:/mr: syntax since the branch already exists.