Skip to content

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

docs(pages): add static command output to sections dominated by GIFs (#2405)

Worktrunk Bot5f126d21fe1b
diff --git a/CLAUDE.md b/CLAUDE.md
index 695c69b6c..14a33c005 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -134,6 +134,8 @@ Documentation has three categories:
3. **Skill-only files** (shell-integration.md, troubleshooting.md):
Edit `skills/worktrunk/reference/` directly — no docs equivalent.
+ When adding a skill-only file, also add a `linguist-generated=false` exemption to `.gitattributes`. The broad `skills/worktrunk/reference/*.md linguist-generated=true` rule marks every skill file as generated, which collapses real edits in GitHub PR diffs — a source of surprise during review (see #2409).
+
### Help text authoring
Help text renders in three contexts — check all three when editing:
diff --git a/README.md b/README.md
index 0528c5ad6..378cdf9b4 100644
--- a/README.md
+++ b/README.md
@@ -144,7 +144,7 @@ Create a worktree for a new feature:
```console
$ wt switch --create feature-auth
-✓ Created branch feature-auth from main and worktree @ repo.feature-auth
+✓ Created branch feature-auth from main and worktree @ ~/repo.feature-auth
```
@@ -186,7 +186,7 @@ $ wt merge main
2 files changed, 53 insertions(+)
✓ Merged to main (1 commit, 2 files, +53)
◎ Removing feature-auth worktree & branch in background (same commit as main, _)
-○ Switched to worktree for main @ repo
+○ Switched to worktree for main @ ~/repo
```
diff --git a/docs/content/hook.md b/docs/content/hook.md
index d09ddd278..69b40f658 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -251,6 +251,33 @@ copy = "wt step copy-ignored"
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.
+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__user_hooks__docs_hook_pre_merge.snap — edit source to update -->
+
+{% terminal(cmd="wt hook pre-merge") %}
+<span class=c>◎</span> <span class=c>Running pre-merge <b>project:test</b></span>
+<span style='background:var(--bright-white,#fff)'> </span> <span class=d><span style='color:var(--blue,#00a)'>cargo</span></span><span class=d> test</span>
+ Finished test [unoptimized + debuginfo] target(s) in 0.12s
+ Running unittests src/lib.rs (target/debug/deps/worktrunk-abc123)
+
+running 18 tests
+test auth::tests::test_jwt_decode ... ok
+test auth::tests::test_jwt_encode ... ok
+test auth::tests::test_token_refresh ... ok
+test auth::tests::test_token_validation ... ok
+
+test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.08s
+<span class=c>◎</span> <span class=c>Running pre-merge <b>project:lint</b></span>
+<span style='background:var(--bright-white,#fff)'> </span> <span class=d><span style='color:var(--blue,#00a)'>cargo</span></span><span class=d> clippy</span>
+ Checking worktrunk v0.1.0
+ Finished dev [unoptimized + debuginfo] target(s) in 1.23s
+{% end %}
+
+<!-- END AUTO-GENERATED -->
+
+{% terminal(cmd="wt hook post-start") %}
+◎ Running post-start: project @ ~/acme
+{% end %}
+
## Passing values
`--KEY=VALUE` binds `KEY` whenever `{{ KEY }}` appears in any command of the hook — the same smart-routing rule `wt <alias>` uses. Built-in variables can be overridden: `--branch=foo` sets `{{ branch }}` inside hook templates (the worktree's actual branch doesn't move). Hyphens in keys become underscores: `--my-var=x` sets `{{ my_var }}`.
diff --git a/docs/content/list.md b/docs/content/list.md
index 9946e345d..5d0f358a9 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -30,18 +30,53 @@ The table renders progressively: branch names, paths, and commit hashes appear i
List all worktrees:
-<!-- wt list -->
-{{ terminal(cmd="wt list") }}
+<!-- ⚠️ 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 -->
Include CI status, line diffs, and LLM summaries:
-<!-- wt list --full -->
-{{ terminal(cmd="wt list --full") }}
+<!-- ⚠️ 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 -->
Include branches that don't have worktrees:
-<!-- wt list --branches --full -->
-{{ terminal(cmd="wt list --branches --full") }}
+<!-- ⚠️ 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 -->
Output as JSON for scripting:
diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.md
index d227cba10..e43b65abd 100644
--- a/docs/content/llm-commits.md
+++ b/docs/content/llm-commits.md
@@ -63,24 +63,65 @@ 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:
+<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__merge__docs_merge_squash_llm.snap — edit source to update -->
+
{% 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="cmd">wt merge</span>
+<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>+16</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> ...
+<span style='background:var(--bright-white,#fff)'> </span>
+<span style='background:var(--bright-white,#fff)'> </span> Add comprehensive JWT token handling including validation, refresh
+<span style='background:var(--bright-white,#fff)'> </span> logic, and authentication tests.
+<span class=g>✓</span> <span class=g>Squashed @ a1b2c3d</span>
+<span class=c>◎</span> <span class=c>Merging 1 commit to <b>main</b> @ <span class=d>a1b2c3d</span> (no rebase needed)</span>
+<span style='background:var(--bright-white,#fff)'> </span> * <span style='color:var(--yellow,#a60)'>a1b2c3d</span> feat(auth): Implement JWT authentication system
+<span style='background:var(--bright-white,#fff)'> </span> auth.rs | 2 <span class=g>++</span>
+<span style='background:var(--bright-white,#fff)'> </span> auth_test.rs | 2 <span class=g>++</span>
+<span style='background:var(--bright-white,#fff)'> </span> integration_test.rs | 6 <span class=g>++++++</span>
+<span style='background:var(--bright-white,#fff)'> </span> jwt.rs | 3 <span class=g>+++</span>
+<span style='background:var(--bright-white,#fff)'> </span> jwt_test.rs | 3 <span class=g>+++</span>
+<span style='background:var(--bright-white,#fff)'> </span> 5 files changed, 16 insertions(+)
+<span class=g>✓</span> <span class=g>Merged to <b>main</b> <span style='color:var(--bright-black,#555)'>(1 commit, 5 files, +16</span></span><span style='color:var(--bright-black,#555)'>)</span>
+<span class=c>◎</span> <span class=c>Removing <b>feature</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 %}
+<!-- END AUTO-GENERATED -->
+
### wt step commit
Stages and commits with LLM-generated message:
-{{ terminal(cmd="wt step commit") }}
+<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__merge__docs_step_commit_llm.snap — edit source to update -->
+
+{% terminal(cmd="wt step commit") %}
+<span class="cmd">wt step commit</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>+26</span></span></span><span style='color:var(--bright-black,#555)'>)</span>
+<span style='background:var(--bright-white,#fff)'> </span> <b>feat(validation): add input validation utilities</b>
+<span class=g>✓</span> <span class=g>Committed changes @ <span class=d>a1b2c3d</span></span>
+{% end %}
+
+<!-- END AUTO-GENERATED -->
### wt step squash
Squashes branch commits into one with LLM-generated message:
-{{ terminal(cmd="wt step squash") }}
+<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__merge__docs_step_squash_llm.snap — edit source to update -->
+
+{% terminal(cmd="wt step squash") %}
+<span class="cmd">wt step squash</span>
+<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>+16</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>
+<span style='background:var(--bright-white,#fff)'> </span> Add comprehensive JWT token handling including validation, refresh
+<span style='background:var(--bright-white,#fff)'> </span> logic, and authentication tests.
+<span class=g>✓</span> <span class=g>Squashed @ a1b2c3d</span>
+{% end %}
+
+<!-- END AUTO-GENERATED -->
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 0b5e4809d..923fc5441 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -24,7 +24,23 @@ Unlike `git merge`, this merges the current branch into the target branch — no
Merge to the default branch:
-{{ terminal(cmd="wt merge") }}
+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__merge__docs_merge_pre_merge_hook.snap — edit source to update -->
+
+{% terminal(cmd="wt merge") %}
+<span class=c>◎</span> <span class=c>Running pre-merge <b>project:test</b></span>
+<span style='background:var(--bright-white,#fff)'> </span> <span class=d><span style='color:var(--blue,#00a)'>cargo</span></span><span class=d> nextest run</span>
+ Finished `test` profile [unoptimized + debuginfo] target(s) in 0.02s
+ Summary [ 0.002s] 2 tests run: 2 passed, 0 skipped
+<span class=c>◎</span> <span class=c>Merging 1 commit to <b>main</b> @ <span class=d>a1b2c3d</span> (no commit/squash/rebase needed)</span>
+<span style='background:var(--bright-white,#fff)'> </span> * <span style='color:var(--yellow,#a60)'>a1b2c3d</span> feat: add hook registration
+<span style='background:var(--bright-white,#fff)'> </span> hook.rs | 31 <span class=g>+++++++++++++++++++++++++++++++</span>
+<span style='background:var(--bright-white,#fff)'> </span> 1 file changed, 31 insertions(+)
+<span class=g>✓</span> <span class=g>Merged to <b>main</b> <span style='color:var(--bright-black,#555)'>(1 commit, 1 file, +31</span></span><span style='color:var(--bright-black,#555)'>)</span>
+<span class=c>◎</span> <span class=c>Removing <b>hooks</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 %}
+
+<!-- END AUTO-GENERATED -->
Merge to a different branch:
diff --git a/docs/content/remove.md b/docs/content/remove.md
index 2f9a6cf4a..6236df3ab 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -15,7 +15,17 @@ Remove worktree; delete branch if merged. Defaults to the current worktree.
Remove current worktree:
-{{ terminal(cmd="wt remove") }}
+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__remove__docs_remove_pre_remove_hook.snap — edit source to update -->
+
+{% terminal(cmd="wt remove") %}
+<span class=c>◎</span> <span class=c>Running pre-remove <b>project:cleanup</b></span>
+<span style='background:var(--bright-white,#fff)'> </span> <span class=d><span style='color:var(--blue,#00a)'>flyctl</span></span><span class=d> scale count 0</span>
+Scaling app to 0 machines
+<span class=c>◎</span> <span class=c>Removing <b>api</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 %}
+
+<!-- END AUTO-GENERATED -->
Remove specific worktrees / branches:
diff --git a/docs/content/step.md b/docs/content/step.md
index 659286452..dfa9f1340 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -15,7 +15,15 @@ Run individual operations. The building blocks of wt merge — commit, squash, r
Commit with LLM-generated message:
-{{ terminal(cmd="wt step commit") }}
+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__merge__docs_step_commit_llm.snap — edit source to update -->
+
+{% terminal(cmd="wt step commit") %}
+<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>+26</span></span></span><span style='color:var(--bright-black,#555)'>)</span>
+<span style='background:var(--bright-white,#fff)'> </span> <b>feat(validation): add input validation utilities</b>
+<span class=g>✓</span> <span class=g>Committed changes @ <span class=d>a1b2c3d</span></span>
+{% end %}
+
+<!-- END AUTO-GENERATED -->
Manual merge workflow with review between steps:
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index d6704f5d0..5715fd5b8 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -139,7 +139,7 @@ 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>
+<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 %}
<!-- END AUTO-GENERATED -->
@@ -183,7 +183,7 @@ When done, either:
<span style='background:var(--bright-white,#fff)'> </span> 2 files changed, 53 insertions(+)
<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>
+<span class=d>○</span> Switched to worktree for <b>main</b> @ <b>~/repo</b>
{% end %}
<!-- END AUTO-GENERATED -->
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 7aa977770..bf251c35b 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -252,6 +252,31 @@ $ wt hook pre-merge -- --extra args # Forward tokens into {{ args }}
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.
+```
+$ wt hook pre-merge
+◎ Running pre-merge project:test
+ cargo test
+ Finished test [unoptimized + debuginfo] target(s) in 0.12s
+ Running unittests src/lib.rs (target/debug/deps/worktrunk-abc123)
+
+running 18 tests
+test auth::tests::test_jwt_decode ... ok
+test auth::tests::test_jwt_encode ... ok
+test auth::tests::test_token_refresh ... ok
+test auth::tests::test_token_validation ... ok
+
+test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.08s
+◎ Running pre-merge project:lint
+ cargo clippy
+ Checking worktrunk v0.1.0
+ Finished dev [unoptimized + debuginfo] target(s) in 1.23s
+```
+
+```bash
+$ wt hook post-start
+◎ Running post-start: project @ ~/acme
+```
+
## Passing values
`--KEY=VALUE` binds `KEY` whenever `{{ KEY }}` appears in any command of the hook — the same smart-routing rule `wt <alias>` uses. Built-in variables can be overridden: `--branch=foo` sets `{{ branch }}` inside hook templates (the worktree's actual branch doesn't move). Hyphens in keys become underscores: `--my-var=x` sets `{{ my_var }}`.
diff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.md
index 3aa2e4903..254bba572 100644
--- a/skills/worktrunk/reference/llm-commits.md
+++ b/skills/worktrunk/reference/llm-commits.md
@@ -51,10 +51,24 @@ Squashes all changes (uncommitted + existing commits) into one commit with an LL
```bash
$ 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>Squashing 3 commits into a single commit <span style='color:var(--bright-black,#555)'>(5 files, <span class=g>+16</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> ...
+<span style='background:var(--bright-white,#fff)'> </span>
+<span style='background:var(--bright-white,#fff)'> </span> Add comprehensive JWT token handling including validation, refresh
+<span style='background:var(--bright-white,#fff)'> </span> logic, and authentication tests.
+<span class=g>✓</span> <span class=g>Squashed @ a1b2c3d</span>
+<span class=c>◎</span> <span class=c>Merging 1 commit to <b>main</b> @ <span class=d>a1b2c3d</span> (no rebase needed)</span>
+<span style='background:var(--bright-white,#fff)'> </span> * <span style='color:var(--yellow,#a60)'>a1b2c3d</span> feat(auth): Implement JWT authentication system
+<span style='background:var(--bright-white,#fff)'> </span> auth.rs | 2 <span class=g>++</span>
+<span style='background:var(--bright-white,#fff)'> </span> auth_test.rs | 2 <span class=g>++</span>
+<span style='background:var(--bright-white,#fff)'> </span> integration_test.rs | 6 <span class=g>++++++</span>
+<span style='background:var(--bright-white,#fff)'> </span> jwt.rs | 3 <span class=g>+++</span>
+<span style='background:var(--bright-white,#fff)'> </span> jwt_test.rs | 3 <span class=g>+++</span>
+<span style='background:var(--bright-white,#fff)'> </span> 5 files changed, 16 insertions(+)
+<span class=g>✓</span> <span class=g>Merged to <b>main</b> <span style='color:var(--bright-black,#555)'>(1 commit, 5 files, +16</span></span><span style='color:var(--bright-black,#555)'>)</span>
+<span class=c>◎</span> <span class=c>Removing <b>feature</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>
```
### wt step commit
@@ -62,7 +76,10 @@ $ wt merge
Stages and commits with LLM-generated message:
```bash
-wt step commit
+$ wt step commit
+<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>+26</span></span></span><span style='color:var(--bright-black,#555)'>)</span>
+<span style='background:var(--bright-white,#fff)'> </span> <b>feat(validation): add input validation utilities</b>
+<span class=g>✓</span> <span class=g>Committed changes @ <span class=d>a1b2c3d</span></span>
```
### wt step squash
@@ -70,7 +87,14 @@ wt step commit
Squashes branch commits into one with LLM-generated message:
```bash
-wt step squash
+$ wt step squash
+<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>+16</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>
+<span style='background:var(--bright-white,#fff)'> </span> Add comprehensive JWT token handling including validation, refresh
+<span style='background:var(--bright-white,#fff)'> </span> logic, and authentication tests.
+<span class=g>✓</span> <span class=g>Squashed @ a1b2c3d</span>
```
See [`wt merge`](https://worktrunk.dev/merge/) and [`wt step`](https://worktrunk.dev/step/) for full documentation.
diff --git a/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.md
index 3fc66e7cd..240fd2f2a 100644
--- a/skills/worktrunk/reference/merge.md
+++ b/skills/worktrunk/reference/merge.md
@@ -8,8 +8,19 @@ Unlike `git merge`, this merges the current branch into the target branch — no
Merge to the default branch:
-```bash
+```
$ wt merge
+◎ Running pre-merge project:test
+ cargo nextest run
+ Finished `test` profile [unoptimized + debuginfo] target(s) in 0.02s
+ Summary [ 0.002s] 2 tests run: 2 passed, 0 skipped
+◎ Merging 1 commit to main @ a1b2c3d (no commit/squash/rebase needed)
+ * a1b2c3d feat: add hook registration
+ hook.rs | 31 +++++++++++++++++++++++++++++++
+ 1 file changed, 31 insertions(+)
+✓ Merged to main (1 commit, 1 file, +31)
+◎ Removing hooks worktree & branch in background (same commit as main, _)
+○ Switched to worktree for main @ ~/repo
```
Merge to a different branch:
diff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.md
index d1ec817f3..709356d9e 100644
--- a/skills/worktrunk/reference/remove.md
+++ b/skills/worktrunk/reference/remove.md
@@ -6,8 +6,13 @@ Remove worktree; delete branch if merged. Defaults to the current worktree.
Remove current worktree:
-```bash
+```
$ wt remove
+◎ Running pre-remove project:cleanup
+ flyctl scale count 0
+Scaling app to 0 machines
+◎ Removing api worktree & branch in background (same commit as main, _)
+○ Switched to worktree for main @ ~/repo
```
Remove specific worktrees / branches:
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 454da1c83..14616f7ee 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -6,8 +6,11 @@ Run individual operations. The building blocks of wt merge — commit, squash, r
Commit with LLM-generated message:
-```bash
+```
$ wt step commit
+◎ Generating commit message and committing changes... (2 files, +26)
+ feat(validation): add input validation utilities
+✓ Committed changes @ a1b2c3d
```
Manual merge workflow with review between steps:
diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.md
index 7ba962ed8..bf77870cc 100644
--- a/skills/worktrunk/reference/worktrunk.md
+++ b/skills/worktrunk/reference/worktrunk.md
@@ -123,7 +123,7 @@ Create a worktree for a new feature:
```bash
$ wt switch --create feature-auth
-<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>
+<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>
```
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/):
@@ -163,7 +163,7 @@ $ wt merge main
<span style='background:var(--bright-white,#fff)'> </span> 2 files changed, 53 insertions(+)
<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>
+<span class=d>○</span> Switched to worktree for <b>main</b> @ <b>~/repo</b>
```
For parallel agents, create multiple worktrees and launch an agent in each:
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index a3fb00efa..6065ffdd9 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -659,6 +659,13 @@ List all worktrees:
<!-- wt list -->
```console
$ wt list
+ Branch Status HEAD± main↕ Remote⇅ Commit Age Message
+@ feature-api + ↕⇡ +54 -5 ↑4 ↓1 ⇡3 6814f02a 30m Add API tests
+^ main ^⇅ ⇡1 ⇣1 41ee0834 4d Merge fix-auth: hardened to…
++ fix-auth ↕| ↑2 ↓1 | b772e68b 5h Add secure token storage
++ fix-typos _| | 41ee0834 4d Merge fix-auth: hardened to…
+
+○ Showing 4 worktrees, 1 with changes, 2 ahead, 1 column hidden
```
Include CI status, line diffs, and LLM summaries:
@@ -666,6 +673,13 @@ Include CI status, line diffs, and LLM summaries:
<!-- wt list --full -->
```console
$ wt list --full
+ Branch Status HEAD± main↕ main…± Summary Remote⇅ CI Commit
+@ feature-api + ↕⇡ +54 -5 ↑4 ↓1 +234 -24 Refactor API to REST architecture with middleware ⇡3 ● 6814f02a
+^ main ^⇅ ⇡1 ⇣1 ● 41ee0834
++ fix-auth ↕| ↑2 ↓1 +25 -11 Harden auth with constant-time token validation | ● b772e68b
++ fix-typos _| | ● 41ee0834
+
+○ Showing 4 worktrees, 1 with changes, 2 ahead, 3 columns hidden
```
Include branches that don't have worktrees:
@@ -673,6 +687,15 @@ Include branches that don't have worktrees:
<!-- wt list --branches --full -->
```console
$ wt list --branches --full
+ Branch Status HEAD± main↕ main…± Summary Remote⇅ CI Commit
+@ feature-api + ↕⇡ +54 -5 ↑4 ↓1 +234 -24 Refactor API to REST architecture with middleware ⇡3 ● 6814f02a
+^ main ^⇅ ⇡1 ⇣1 ● 41ee0834
++ fix-auth ↕| ↑2 ↓1 +25 -11 Harden auth with constant-time token validation | ● b772e68b
++ fix-typos _| | ● 41ee0834
+ exp /↕ ↑2 ↓1 +137 Explore GraphQL schema and resolvers 96379229
+ wip /↕ ↑1 ↓1 +33 Start API documentation b40716dc
+
+○ Showing 4 worktrees, 2 branches, 1 with changes, 4 ahead, 3 columns hidden
```
Output as JSON for scripting:
@@ -908,8 +931,14 @@ Missing a field that would be generally useful? Open an issue at https://github.
Remove current worktree:
+<!-- wt remove (docs-example) -->
```console
$ wt remove
+◎ Running pre-remove project:cleanup
+ flyctl scale count 0
+Scaling app to 0 machines
+◎ Removing api worktree & branch in background (same commit as main, _)
+○ Switched to worktree for main @ ~/repo
```
Remove specific worktrees / branches:
@@ -997,8 +1026,20 @@ Detached worktrees have no branch name. Pass the worktree path instead: `wt remo
Merge to the default branch:
+<!-- wt merge (docs-example) -->
```console
$ wt merge
+◎ Running pre-merge project:test
+ cargo nextest run
+ Finished `test` profile [unoptimized + debuginfo] target(s) in 0.02s
+ Summary [ 0.002s] 2 tests run: 2 passed, 0 skipped
+◎ Merging 1 commit to main @ a1b2c3d (no commit/squash/rebase needed)
+ * a1b2c3d feat: add hook registration
+ hook.rs | 31 +++++++++++++++++++++++++++++++
+ 1 file changed, 31 insertions(+)
+✓ Merged to main (1 commit, 1 file, +31)
+◎ Removing hooks worktree & branch in background (same commit as main, _)
+○ Switched to worktree for main @ ~/repo
```
Merge to a different branch:
@@ -1092,8 +1133,12 @@ lint = "cargo clippy"
Commit with LLM-generated message:
+<!-- wt step commit (docs-example) -->
```console
$ wt step commit
+◎ Generating commit message and committing changes... (2 files, +26)
+ feat(validation): add input validation utilities
+✓ Committed changes @ a1b2c3d
```
Manual merge workflow with review between steps:
@@ -1393,6 +1438,32 @@ $ wt hook pre-merge -- --extra args # Forward tokens into {{ args }}
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.
+<!-- wt hook pre-merge (docs-example) -->
+```console
+$ wt hook pre-merge
+◎ Running pre-merge project:test
+ cargo test
+ Finished test [unoptimized + debuginfo] target(s) in 0.12s
+ Running unittests src/lib.rs (target/debug/deps/worktrunk-abc123)
+
+running 18 tests
+test auth::tests::test_jwt_decode ... ok
+test auth::tests::test_jwt_encode ... ok
+test auth::tests::test_token_refresh ... ok
+test auth::tests::test_token_validation ... ok
+
+test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.08s
+◎ Running pre-merge project:lint
+ cargo clippy
+ Checking worktrunk v0.1.0
+ Finished dev [unoptimized + debuginfo] target(s) in 1.23s
+```
+
+```console
+$ wt hook post-start
+◎ Running post-start: project @ ~/acme
+```
+
## Passing values
`--KEY=VALUE` binds `KEY` whenever `{{ KEY }}` appears in any command of the hook — the same smart-routing rule `wt <alias>` uses. Built-in variables can be overridden: `--branch=foo` sets `{{ branch }}` inside hook templates (the worktree's actual branch doesn't move). Hyphens in keys become underscores: `--my-var=x` sets `{{ my_var }}`.
diff --git a/src/docs.rs b/src/docs.rs
index 87942e865..65366e8bc 100644
--- a/src/docs.rs
+++ b/src/docs.rs
@@ -4,6 +4,26 @@
//! shortcodes. Used by both the `--help-page` generator (CLI source → web docs)
//! and the doc sync test (hand-written docs → web docs).
+/// Empty span; the displayed "EXPERIMENTAL" text comes from the CSS `::after`
+/// rule so the anchor-link slug generated by Zola ignores it.
+///
+/// Lives here (rather than in `src/help.rs`) so the producer (the `--help-page`
+/// post-processor that emits this in place of `[experimental]`) and the
+/// consumer (the skill-file generator that strips it back to `[experimental]`)
+/// stay in lockstep — changing the badge in one place would otherwise let
+/// stale HTML leak silently into skill files.
+pub const BADGE_EXPERIMENTAL_HTML: &str = "<span class=\"badge-experimental\"></span>";
+
+/// HTML-comment marker that includes a subcommand's `--help-page` body inline
+/// in its parent's `after_long_help`. Expanded into an H2 section by
+/// `expand_subdoc_placeholders`. Trailing space included so `find()` and
+/// `strip_prefix()` agree on the boundary.
+pub const SUBDOC_MARKER_PREFIX: &str = "<!-- subdoc: ";
+
+/// HTML-comment marker that pulls a demo GIF from `worktrunk-assets` into the
+/// docs site (rendered as a `<picture>` figure). Stripped from skill output.
+pub const DEMO_MARKER_PREFIX: &str = "<!-- demo: ";
+
/// Convert `$ `‐prefixed console blocks into `{% terminal() %}` shortcodes.
///
/// All shell commands in `console` blocks use `$ ` prefix. This function detects
diff --git a/src/help.rs b/src/help.rs
index 7f44c8175..51992ba62 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -50,15 +50,14 @@ use std::process;
use ansi_str::AnsiStr;
use clap::ColorChoice;
use clap::error::ErrorKind;
-use worktrunk::docs::convert_dollar_console_to_terminal;
+use worktrunk::docs::{
+ BADGE_EXPERIMENTAL_HTML, DEMO_MARKER_PREFIX, SUBDOC_MARKER_PREFIX,
+ convert_dollar_console_to_terminal,
+};
use worktrunk::styling::{eprintln, println};
use crate::cli;
-/// Empty span; the displayed "EXPERIMENTAL" text comes from the CSS `::after`
-/// rule so the anchor-link slug generated by Zola ignores it.
-const BADGE_EXPERIMENTAL_HTML: &str = "<span class=\"badge-experimental\"></span>";
-
/// Output format for a `--help-page`. Web pages keep Zola shortcodes, HTML
/// spans, and demo GIF figures for the docs site; plain pages strip those for
/// skill reference files that need portable markdown.
@@ -206,14 +205,7 @@ pub fn maybe_handle_help_with_pager(alias_help_context: Option<crate::commands::
ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
)
{
- // Transform code block languages for Zola compatibility:
- // - ```text (clap's default for usage) -> ``` (no highlighting)
- // - ```console (our examples) -> ```bash
- let output = err
- .render()
- .to_string()
- .replace("```text\n", "```\n")
- .replace("```console\n", "```bash\n");
+ let output = normalize_clap_help_fences(&err.render().to_string());
print!("{output}");
process::exit(0);
}
@@ -289,6 +281,18 @@ fn help_reference_with_color(
}
}
+/// Normalize fences in clap-rendered help output for downstream markdown
+/// consumers. `--help-md` and `help_reference_inner` both run this; the lone
+/// `console`→`bash` use in `PageMode::transform_raw` doesn't, because its input
+/// is `after_long_help` markdown which never contains clap's `text` blocks.
+fn normalize_clap_help_fences(text: &str) -> String {
+ text
+ // clap's default for usage blocks — strip the language for plain markdown
+ .replace("```text\n", "```\n")
+ // our authored examples — relabel for syntax highlighting in docs/skills
+ .replace("```console\n", "```bash\n")
+}
+
fn help_reference_inner(command_path: &[&str], width: Option<usize>, color: ColorChoice) -> String {
// Build args: ["wt", "config", "create", "--help"]
let mut args: Vec<String> = vec!["wt".to_string()];
@@ -315,8 +319,7 @@ fn help_reference_inner(command_path: &[&str], width: Option<usize>, color: Colo
} else {
rendered.to_string()
};
- text.replace("```text\n", "```\n")
- .replace("```console\n", "```bash\n")
+ normalize_clap_help_fences(&text)
} else {
return String::new();
};
@@ -485,7 +488,7 @@ Commands with pages: merge, switch, remove, list"
let raw_help = mode.transform_raw(combine_command_docs(sub));
// Subdocs are expanded separately so the main command reference comes first.
- let (main_content, subdoc_content) = match raw_help.find("<!-- subdoc:") {
+ let (main_content, subdoc_content) = match raw_help.find(SUBDOC_MARKER_PREFIX) {
Some(pos) => (&raw_help[..pos], Some(&raw_help[pos..])),
None => (raw_help.as_str(), None),
};
@@ -684,12 +687,11 @@ fn expand_subdoc_placeholders(
parent_name: &str,
mode: PageMode,
) -> String {
- const PREFIX: &str = "<!-- subdoc: ";
const SUFFIX: &str = " -->";
let mut result = text.to_string();
- while let Some(start) = result.find(PREFIX) {
- let after_prefix = start + PREFIX.len();
+ while let Some(start) = result.find(SUBDOC_MARKER_PREFIX) {
+ let after_prefix = start + SUBDOC_MARKER_PREFIX.len();
if let Some(end_offset) = result[after_prefix..].find(SUFFIX) {
let subcommand_name = result[after_prefix..after_prefix + end_offset].trim();
let end = after_prefix + end_offset + SUFFIX.len();
@@ -764,7 +766,7 @@ fn format_subcommand_section(
};
// Split content at first subdoc placeholder so command reference comes before nested subdocs
- let (main_content, subdoc_content) = match raw_help.find("<!-- subdoc:") {
+ let (main_content, subdoc_content) = match raw_help.find(SUBDOC_MARKER_PREFIX) {
Some(pos) => (&raw_help[..pos], Some(&raw_help[pos..])),
None => (raw_help.as_str(), None),
};
@@ -821,12 +823,11 @@ fn format_subcommand_section(
///
/// Supports optional dimensions: `<!-- demo: filename.gif 1600x900 -->`
fn expand_demo_placeholders(text: &str) -> String {
- const PREFIX: &str = "<!-- demo: ";
const SUFFIX: &str = " -->";
let mut result = text.to_string();
- while let Some(start) = result.find(PREFIX) {
- let after_prefix = start + PREFIX.len();
+ while let Some(start) = result.find(DEMO_MARKER_PREFIX) {
+ let after_prefix = start + DEMO_MARKER_PREFIX.len();
if let Some(end_offset) = result[after_prefix..].find(SUFFIX) {
let content = &result[after_prefix..after_prefix + end_offset];
// Parse "filename.gif" or "filename.gif 1600x900"
@@ -864,12 +865,11 @@ fn expand_demo_placeholders(text: &str) -> String {
/// Removes `<!-- demo: filename.gif -->` lines entirely. These are invisible in
/// terminal --help but would leak as HTML comments in skill reference files.
fn strip_demo_placeholders(text: &str) -> String {
- const PREFIX: &str = "<!-- demo: ";
const SUFFIX: &str = " -->";
let mut result = text.to_string();
- while let Some(start) = result.find(PREFIX) {
- let after_prefix = start + PREFIX.len();
+ while let Some(start) = result.find(DEMO_MARKER_PREFIX) {
+ let after_prefix = start + DEMO_MARKER_PREFIX.len();
if let Some(end_offset) = result[after_prefix..].find(SUFFIX) {
let end = after_prefix + end_offset + SUFFIX.len();
// Also strip trailing newline if present
diff --git a/tests/integration_tests/merge.rs b/tests/integration_tests/merge.rs
index 4278a8f90..43ca3ae1a 100644
--- a/tests/integration_tests/merge.rs
+++ b/tests/integration_tests/merge.rs
@@ -1218,6 +1218,294 @@ command = "{llm_path_str}"
// were removed - they're covered by PTY-based tests in shell_wrapper.rs that capture
// combined stdout/stderr for README examples.
+// ============================================================================
+// Docs-page example snapshots
+//
+// These drive the static command-output blocks on docs pages that are otherwise
+// dominated by GIFs (merge.md, step.md, remove.md, hook.md). Each snapshot is
+// threaded into the corresponding page via a `<!-- wt <cmd> (docs-example) -->`
+// marker in `src/cli/mod.rs`; `readme_sync.rs` writes the plain output back
+// into the source (for terminal `--help`) and also renders the colorized form
+// for the docs site. Keep these scenarios realistic and concise — the output
+// appears on public pages.
+// ============================================================================
+
+/// `wt merge` example for `docs/content/merge.md` — pre-merge hook running
+/// `cargo nextest run`, one-commit fast-forward merge, background cleanup.
+#[rstest]
+fn test_docs_merge_pre_merge_hook(mut repo: TestRepo) {
+ repo.run_git(&["config", "worktrunk.hints.worktree-path", "true"]);
+
+ let bin_dir = repo.root_path().join(".bin");
+ fs::create_dir_all(&bin_dir).unwrap();
+ crate::common::mock_commands::MockConfig::new("cargo")
+ .command(
+ "nextest",
+ crate::common::mock_commands::MockResponse::output(
+ " Finished `test` profile [unoptimized + debuginfo] target(s) in 0.02s
+ Summary [ 0.002s] 2 tests run: 2 passed, 0 skipped
+",
+ ),
+ )
+ .write(&bin_dir);
+
+ let config_dir = repo.root_path().join(".config");
+ fs::create_dir_all(&config_dir).unwrap();
+ fs::write(
+ config_dir.join("wt.toml"),
+ r#"[[pre-merge]]
+test = "cargo nextest run"
+"#,
+ )
+ .unwrap();
+ repo.run_git(&["add", ".config/wt.toml", ".bin"]);
+ repo.run_git(&["commit", "-m", "Add project config"]);
+
+ let feature_wt = repo.add_worktree_with_commit(
+ "hooks",
+ "hook.rs",
+ r#"//! Hook registration and dispatch.
+
+use std::collections::HashMap;
+
+/// A named hook handler.
+pub struct Hook {
+ pub name: String,
+ pub kind: HookKind,
+}
+
+/// Hook invocation phase.
+pub enum HookKind {
+ PreMerge,
+ PreRemove,
+ PostStart,
+}
+
+/// Registry of hooks keyed by name.
+pub struct Registry {
+ hooks: HashMap<String, Hook>,
+}
+
+impl Registry {
+ pub fn new() -> Self {
+ Self { hooks: HashMap::new() }
+ }
+
+ pub fn register(&mut self, hook: Hook) {
+ self.hooks.insert(hook.name.clone(), hook);
+ }
+}
+"#,
+ "feat: add hook registration",
+ );
+
+ let directive_file = repo
+ .root_path()
+ .parent()
+ .unwrap()
+ .join(".wt-directive-docs-merge");
+ fs::write(&directive_file, "").unwrap();
+
+ let (path_var, path_with_bin) = make_path_with_mock_bin(&bin_dir);
+ let bin_dir_str = bin_dir.to_string_lossy();
+ let directive_file_str = directive_file.to_string_lossy().into_owned();
+ snapshot_merge_with_env(
+ "docs_merge_pre_merge_hook",
+ &repo,
+ &["--yes"],
+ Some(&feature_wt),
+ &[
+ (&path_var, &path_with_bin),
+ ("MOCK_CONFIG_DIR", &bin_dir_str),
+ ("WORKTRUNK_DIRECTIVE_CD_FILE", &directive_file_str),
+ ],
+ );
+}
+
+/// `wt merge` example for `docs/content/llm-commits.md` — three commits
+/// squashed with an LLM-generated message, then merged to default branch.
+#[rstest]
+fn test_docs_merge_squash_llm(mut repo: TestRepo) {
+ repo.run_git(&["config", "worktrunk.hints.worktree-path", "true"]);
+
+ let feature_wt = repo.add_worktree("feature");
+
+ fs::write(
+ feature_wt.join("auth.rs"),
+ "pub fn refresh(token: &str) -> String { token.to_string() }\npub fn validate_signature(_: &str) -> bool { true }\n",
+ )
+ .unwrap();
+ fs::write(
+ feature_wt.join("auth_test.rs"),
+ "use super::*;\n#[test] fn refresh_rotates() { assert_eq!(refresh(\"t\"), \"t\"); }\n",
+ )
+ .unwrap();
+ repo.run_git_in(&feature_wt, &["add", "auth.rs", "auth_test.rs"]);
+ repo.run_git_in(&feature_wt, &["commit", "-m", "Add token refresh logic"]);
+
+ fs::write(
+ feature_wt.join("jwt.rs"),
+ "pub fn decode_claims(token: &str) -> Option<&str> { token.split('.').nth(1) }\npub fn encode(payload: &str) -> String { format!(\"h.{}.s\", payload) }\npub fn verify(_: &str, _: &str) -> bool { true }\n",
+ )
+ .unwrap();
+ fs::write(
+ feature_wt.join("jwt_test.rs"),
+ "use super::*;\n#[test] fn decode_returns_payload() { assert_eq!(decode_claims(\"h.p.s\"), Some(\"p\")); }\n#[test] fn encode_wraps_payload() { assert_eq!(encode(\"p\"), \"h.p.s\"); }\n",
+ )
+ .unwrap();
+ repo.run_git_in(&feature_wt, &["add", "jwt.rs", "jwt_test.rs"]);
+ repo.run_git_in(&feature_wt, &["commit", "-m", "Implement JWT validation"]);
+
+ fs::write(
+ feature_wt.join("integration_test.rs"),
+ "use super::*;\n#[test] fn full_auth_flow() {\n let tok = refresh(\"seed\");\n assert!(validate_signature(&tok));\n assert!(verify(&tok, \"sig\"));\n}\n",
+ )
+ .unwrap();
+ repo.run_git_in(&feature_wt, &["add", "integration_test.rs"]);
+ repo.run_git_in(&feature_wt, &["commit", "-m", "Add authentication tests"]);
+
+ let squash_message = "feat(auth): Implement JWT authentication system
+
+Add comprehensive JWT token handling including validation, refresh
+logic, and authentication tests.";
+
+ let directive_file = repo
+ .root_path()
+ .parent()
+ .unwrap()
+ .join(".wt-directive-docs-merge-squash");
+ fs::write(&directive_file, "").unwrap();
+ let directive_file_str = directive_file.to_string_lossy().into_owned();
+
+ snapshot_merge_with_env(
+ "docs_merge_squash_llm",
+ &repo,
+ &[],
+ Some(&feature_wt),
+ &[
+ (
+ "WORKTRUNK_COMMIT__GENERATION__COMMAND",
+ &format!("cat >/dev/null && echo '{squash_message}'"),
+ ),
+ ("WORKTRUNK_DIRECTIVE_CD_FILE", &directive_file_str),
+ ],
+ );
+}
+
+/// `wt step squash` example for `docs/content/llm-commits.md` — three commits
+/// squashed with an LLM-generated message.
+#[rstest]
+fn test_docs_step_squash_llm(mut repo: TestRepo) {
+ repo.run_git(&["config", "worktrunk.hints.worktree-path", "true"]);
+
+ let feature_wt = repo.add_worktree("feature");
+
+ // Three commits in the feature worktree, totaling ~48 lines across 5 files.
+ fs::write(
+ feature_wt.join("auth.rs"),
+ "pub fn refresh(token: &str) -> String { token.to_string() }\npub fn validate_signature(_: &str) -> bool { true }\n",
+ )
+ .unwrap();
+ fs::write(
+ feature_wt.join("auth_test.rs"),
+ "use super::*;\n#[test] fn refresh_rotates() { assert_eq!(refresh(\"t\"), \"t\"); }\n",
+ )
+ .unwrap();
+ repo.run_git_in(&feature_wt, &["add", "auth.rs", "auth_test.rs"]);
+ repo.run_git_in(&feature_wt, &["commit", "-m", "Add token refresh logic"]);
+
+ fs::write(
+ feature_wt.join("jwt.rs"),
+ "pub fn decode_claims(token: &str) -> Option<&str> { token.split('.').nth(1) }\npub fn encode(payload: &str) -> String { format!(\"h.{}.s\", payload) }\npub fn verify(_: &str, _: &str) -> bool { true }\n",
+ )
+ .unwrap();
+ fs::write(
+ feature_wt.join("jwt_test.rs"),
+ "use super::*;\n#[test] fn decode_returns_payload() { assert_eq!(decode_claims(\"h.p.s\"), Some(\"p\")); }\n#[test] fn encode_wraps_payload() { assert_eq!(encode(\"p\"), \"h.p.s\"); }\n",
+ )
+ .unwrap();
+ repo.run_git_in(&feature_wt, &["add", "jwt.rs", "jwt_test.rs"]);
+ repo.run_git_in(&feature_wt, &["commit", "-m", "Implement JWT validation"]);
+
+ fs::write(
+ feature_wt.join("integration_test.rs"),
+ "use super::*;\n#[test] fn full_auth_flow() {\n let tok = refresh(\"seed\");\n assert!(validate_signature(&tok));\n assert!(verify(&tok, \"sig\"));\n}\n",
+ )
+ .unwrap();
+ repo.run_git_in(&feature_wt, &["add", "integration_test.rs"]);
+ repo.run_git_in(&feature_wt, &["commit", "-m", "Add authentication tests"]);
+
+ let squash_message = "feat(auth): Implement JWT authentication system
+
+Add comprehensive JWT token handling including validation, refresh
+logic, and authentication tests.";
+
+ assert_cmd_snapshot!("docs_step_squash_llm", {
+ let mut cmd = make_snapshot_cmd(&repo, "step", &["squash"], Some(&feature_wt));
+ cmd.env(
+ "WORKTRUNK_COMMIT__GENERATION__COMMAND",
+ format!("cat >/dev/null && echo '{squash_message}'"),
+ );
+ cmd
+ });
+}
+
+/// `wt step commit` example for `docs/content/step.md` and `docs/content/llm-commits.md`.
+/// Feature worktree with two staged files + LLM-generated commit message.
+#[rstest]
+fn test_docs_step_commit_llm(mut repo: TestRepo) {
+ repo.run_git(&["config", "worktrunk.hints.worktree-path", "true"]);
+
+ let feature_wt = repo.add_worktree("feature");
+
+ fs::write(
+ feature_wt.join("validation.rs"),
+ r#"//! Input validation helpers.
+
+/// Returns true if the value is strictly positive.
+pub fn is_positive(n: i64) -> bool {
+ n > 0
+}
+
+/// Returns true if the string has at least one non-whitespace character.
+pub fn is_non_empty(s: &str) -> bool {
+ !s.trim().is_empty()
+}
+"#,
+ )
+ .unwrap();
+ fs::write(
+ feature_wt.join("validation_test.rs"),
+ r#"use super::*;
+
+#[test]
+fn accepts_positive_numbers() {
+ assert!(is_positive(1));
+ assert!(!is_positive(0));
+ assert!(!is_positive(-1));
+}
+
+#[test]
+fn accepts_non_empty_strings() {
+ assert!(is_non_empty("hello"));
+ assert!(!is_non_empty(""));
+ assert!(!is_non_empty(" "));
+}
+"#,
+ )
+ .unwrap();
+ repo.run_git_in(&feature_wt, &["add", "validation.rs", "validation_test.rs"]);
+
+ assert_cmd_snapshot!("docs_step_commit_llm", {
+ let mut cmd = make_snapshot_cmd(&repo, "step", &["commit"], Some(&feature_wt));
+ cmd.env(
+ "WORKTRUNK_COMMIT__GENERATION__COMMAND",
+ "cat >/dev/null && echo 'feat(validation): add input validation utilities'",
+ );
+ cmd
+ });
+}
+
#[rstest]
fn test_merge_no_commit_with_clean_tree(mut repo_with_feature_worktree: TestRepo) {
let repo = &mut repo_with_feature_worktree;
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index b5ab6a52e..e4091c69b 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -283,20 +283,20 @@ fn extract_command_from_snapshot(content: &str) -> Option<String> {
/// - `[TMPDIR]/repo.branch` → `../repo.branch`
/// - `[TMPDIR]/repo` → `../repo`
/// - `[REPO]` → `../repo`
-/// - `_REPO_` → `repo` (just the repo name, no path)
-/// - `_REPO_.branch` → `repo.branch`
+/// - `_REPO_` → `~/repo` (worktree path; tilde so it reads as a path, not a project name)
+/// - `_REPO_.branch` → `~/repo.branch`
fn replace_placeholders(content: &str) -> String {
let content = HASH_REGEX.replace_all(content, "a1b2c3d");
let content = TMPDIR_BRANCH_REGEX.replace_all(&content, "../repo.$1");
let content = TMPDIR_MAIN_REGEX.replace_all(&content, "../repo$1");
let content = REPO_REGEX.replace_all(&content, "../repo");
- // Handle _REPO_.branch -> repo.branch and _REPO_ -> repo
+ // Handle _REPO_.branch -> ~/repo.branch and _REPO_ -> ~/repo
REPO_UNDERSCORE_REGEX
.replace_all(&content, |caps: &regex::Captures| {
if let Some(branch) = caps.get(2) {
- format!("repo.{}", branch.as_str())
+ format!("~/repo.{}", branch.as_str())
} else {
- "repo".to_string()
+ "~/repo".to_string()
}
})
.into_owned()
@@ -384,19 +384,30 @@ fn update_section(
// =============================================================================
/// Regex to find command placeholder comments in help pages.
-/// Matches: `<!-- wt <id> -->\n```bash\n[$ ]wt <cmd>\n```` — the `$ ` prompt is
-/// optional. Group 1 captures the placeholder id (used for snapshot lookup,
-/// e.g. `wt list (markers)`); group 2 captures the actual command to display
-/// (e.g. `wt list`).
///
-/// Pattern expects ```bash``` because --help-page converts ```console``` first.
-/// In HTML mode the `$ ` alternative is a no-op today because
-/// `convert_dollar_console_to_terminal` has already rewritten `$ `‐prefixed
-/// console blocks into `{{ terminal }}` shortcodes upstream, and no raw
-/// ```bash``` blocks with a `$ ` prompt exist in CLI `after_long_help` source;
-/// plain mode skips that conversion, so both forms reach this regex.
+/// A placeholder is an HTML comment `<!-- wt <id> -->` followed by one of three
+/// code-block forms (the form depends on which stage of `--help-page` has run):
+///
+/// - ````bash``` with an optional `$ ` prompt, optionally followed by multi-line
+/// output — this is what plain (`--help-page --plain`) output contains, and
+/// also what `cli/mod.rs` source contains before `convert_dollar_console_to_terminal`.
+/// - `{{ terminal(cmd="...") }}` self-closing Zola shortcode — produced by
+/// `convert_dollar_console_to_terminal` when the source block has only a command.
+/// - `{% terminal(cmd="...") %}…{% end %}` Zola shortcode — produced by
+/// `convert_dollar_console_to_terminal` when the source block has output too.
+///
+/// Capture groups:
+/// 1. placeholder id (e.g. `wt list (markers)`) — drives snapshot lookup
+/// 2. display command when matched in the ```bash form
+/// 3. display command when matched as `{{ terminal() }}`
+/// 4. display command when matched as `{% terminal() %}…{% end %}`
+///
+/// Exactly one of groups 2–4 is non-None per match.
static COMMAND_PLACEHOLDER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
- Regex::new(r"<!-- (wt [^>]+) -->\n```bash\n(?:\$ )?(wt [^\n]+)\n```").unwrap()
+ Regex::new(
+ r#"(?s)<!-- (wt [^>\n]+) -->\n(?:```bash\n(?:\$ )?(wt [^\n]+).*?\n```|\{\{ terminal\(cmd="(wt [^"]+)"\) \}\}|\{% terminal\(cmd="(wt [^"]+)"\) %\}.*?\{% end %\})"#,
+ )
+ .unwrap()
});
/// Map commands to their snapshot files for help page expansion
@@ -412,6 +423,21 @@ fn command_to_snapshot(command: &str) -> Option<&'static str> {
"wt list (markers)" => {
Some("integration__integration_tests__list__readme_example_list_marker.snap")
}
+ // Docs-page example snapshots — drive the static command-output blocks
+ // on pages otherwise dominated by GIFs. See comment in merge.rs test
+ // section for the convention.
+ "wt merge (docs-example)" => {
+ Some("integration__integration_tests__merge__docs_merge_pre_merge_hook.snap")
+ }
+ "wt step commit (docs-example)" => {
+ Some("integration__integration_tests__merge__docs_step_commit_llm.snap")
+ }
+ "wt remove (docs-example)" => {
+ Some("integration__integration_tests__remove__docs_remove_pre_remove_hook.snap")
+ }
+ "wt hook pre-merge (docs-example)" => {
+ Some("integration__integration_tests__user_hooks__docs_hook_pre_merge.snap")
+ }
_ => None,
}
}
@@ -446,7 +472,19 @@ fn expand_command_placeholders(
for cap in COMMAND_PLACEHOLDER_PATTERN.captures_iter(content) {
let full_match = cap.get(0).unwrap().as_str();
let placeholder_id = cap.get(1).unwrap().as_str();
- let display_cmd = cap.get(2).unwrap().as_str();
+ // Exactly one of groups 2–4 matched — pick whichever.
+ let raw_display_cmd = cap
+ .get(2)
+ .or_else(|| cap.get(3))
+ .or_else(|| cap.get(4))
+ .unwrap()
+ .as_str();
+ // Strip trailing `|||` delimiters: `convert_dollar_console_to_terminal`
+ // treats blank lines in a ```console``` body as extra empty commands and
+ // appends them to the `cmd=` parameter with `|||` separators. Those
+ // empties would render as a stray `$ ` prompt in the Zola terminal
+ // template.
+ let display_cmd = raw_display_cmd.trim_end_matches('|').trim_end();
let Some(snapshot_name) = command_to_snapshot(placeholder_id) else {
continue;
@@ -1667,6 +1705,7 @@ fn test_docs_quickstart_examples_are_in_sync() {
"docs/content/worktrunk.md",
"docs/content/claude-code.md",
"docs/content/tips-patterns.md",
+ "docs/content/llm-commits.md",
];
let mut all_errors = Vec::new();
@@ -2024,12 +2063,12 @@ fn transform_docs_for_skill(content: &str) -> String {
// Strip HTML figure elements (demo GIFs)
let content = HTML_FIGURE_PATTERN.replace_all(&content, "");
- // Replace experimental markers (shortcode and HTML badge) with plain text
+ // Replace experimental markers (shortcode and HTML badge) with plain text.
+ // Sourcing the badge HTML from `worktrunk::docs` keeps producer (help.rs)
+ // and consumer (this strip) in lockstep: a format change there breaks
+ // here at compile time rather than silently leaking HTML into skills.
let content = ZOLA_EXPERIMENTAL_SHORTCODE.replace_all(&content, "[experimental]");
- let content = content.replace(
- "<span class=\"badge-experimental\"></span>",
- "[experimental]",
- );
+ let content = content.replace(worktrunk::docs::BADGE_EXPERIMENTAL_HTML, "[experimental]");
// Prepend title as H1 if extracted
let content = if let Some(title) = title {
@@ -2330,6 +2369,104 @@ fn sync_well_known_skills(project_root: &Path) -> Vec<String> {
updated_files
}
+/// Regex for `<!-- wt <id> -->\n```console\n$ <cmd>\n[body]\n``` ` blocks in
+/// `src/cli/mod.rs`. The body is anything between the command line and the
+/// closing fence, captured non-greedily so adjacent blocks don't overlap.
+///
+/// Capture groups:
+/// 1. placeholder id
+/// 2. display command (the `$ ...` line)
+/// 3. body — multiline output lines (may be empty when the placeholder is a
+/// freshly added stub with no snapshot filled in yet).
+static CLI_MOD_EXAMPLE_BODY_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
+ Regex::new(r"(?s)<!-- (wt [^>\n]+) -->\n```console\n\$ (wt [^\n]+)\n(.*?)```").unwrap()
+});
+
+/// Fill the body of each `<!-- wt <id> -->`-tagged ```console``` block in
+/// `src/cli/mod.rs` with the plain-text output of the snapshot registered for
+/// that id. This is the write-back half of the docs-example pipeline: it keeps
+/// the terminal `--help` output (which is served verbatim from the source)
+/// faithful to real command output without requiring hand maintenance.
+///
+/// Runs before `sync_command_pages` so `--help-page` sees the fresh bodies.
+fn sync_cli_mod_example_bodies(project_root: &Path) -> (Vec<String>, Vec<String>) {
+ let mut errors = Vec::new();
+ let mut updated_files = Vec::new();
+
+ let cli_mod_path = project_root.join("src/cli/mod.rs");
+ let content = match fs::read_to_string(&cli_mod_path) {
+ Ok(c) => c,
+ Err(e) => {
+ errors.push(format!("Failed to read {}: {}", cli_mod_path.display(), e));
+ return (errors, updated_files);
+ }
+ };
+ let snapshots_dir = project_root.join("tests/snapshots");
+
+ // Collect matches first to replace in reverse (preserves byte offsets).
+ let matches: Vec<_> = CLI_MOD_EXAMPLE_BODY_PATTERN
+ .captures_iter(&content)
+ .map(|cap| {
+ let m = cap.get(0).unwrap();
+ (
+ m.start(),
+ m.end(),
+ cap.get(1).unwrap().as_str().to_string(),
+ cap.get(2).unwrap().as_str().to_string(),
+ cap.get(3).unwrap().as_str().to_string(),
+ )
+ })
+ .collect();
+
+ let mut new_content = content.clone();
+ for (start, end, placeholder_id, display_cmd, current_body) in matches.into_iter().rev() {
+ let Some(snapshot_name) = command_to_snapshot(&placeholder_id) else {
+ continue;
+ };
+
+ let snapshot_path = snapshots_dir.join(snapshot_name);
+ let snapshot_content = match fs::read_to_string(&snapshot_path) {
+ Ok(c) => c,
+ Err(e) => {
+ errors.push(format!(
+ "Failed to read {}: {} (for placeholder '{}')",
+ snapshot_path.display(),
+ e,
+ placeholder_id
+ ));
+ continue;
+ }
+ };
+
+ let plain = trim_lines(&parse_snapshot_content_for_skill(&snapshot_content));
+ // Body ends with a newline before the closing fence; match the source
+ // convention so we don't churn whitespace on subsequent runs.
+ let new_body = if plain.is_empty() {
+ String::new()
+ } else {
+ format!("{plain}\n")
+ };
+ let replacement =
+ format!("<!-- {placeholder_id} -->\n```console\n$ {display_cmd}\n{new_body}```",);
+
+ // Compare normalized bodies (trim each line of trailing whitespace) so
+ // pre-commit's trailing-whitespace trimmer doesn't create infinite loops.
+ if trim_lines(&current_body) != trim_lines(&new_body) {
+ new_content.replace_range(start..end, &replacement);
+ }
+ }
+
+ if new_content != content {
+ if let Err(e) = fs::write(&cli_mod_path, &new_content) {
+ errors.push(format!("Failed to write {}: {}", cli_mod_path.display(), e));
+ } else {
+ updated_files.push("src/cli/mod.rs".to_string());
+ }
+ }
+
+ (errors, updated_files)
+}
+
/// Generate `docs/static/llms.txt` from `docs/content/*.md` front-matter,
/// following the llms.txt spec (https://llmstxt.org/): H1, blockquote summary,
/// optional intro prose, H2 section headings with bulleted link lists.
@@ -2478,6 +2615,11 @@ fn extract_intro_prose(body: &str) -> String {
fn test_command_pages_and_skill_files_are_in_sync() {
let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
+ // Step 0: Fill docs-example bodies in src/cli/mod.rs from snapshots. Runs
+ // before --help-page reads the file so command pages and skill files see
+ // the up-to-date content.
+ let (mod_errors, mod_files) = sync_cli_mod_example_bodies(project_root);
+
// Step 1: Sync command pages (mod.rs → docs/content/*.md)
let (cmd_errors, cmd_files) = sync_command_pages(project_root);
@@ -2497,9 +2639,14 @@ fn test_command_pages_and_skill_files_are_in_sync() {
let llms_files = sync_llms_txt(project_root);
// Aggregate results
- let all_errors: Vec<_> = cmd_errors.into_iter().chain(skill_errors).collect();
- let all_files: Vec<_> = cmd_files
+ let all_errors: Vec<_> = mod_errors
+ .into_iter()
+ .chain(cmd_errors)
+ .chain(skill_errors)
+ .collect();
+ let all_files: Vec<_> = mod_files
.into_iter()
+ .chain(cmd_files)
.chain(console_files)
.chain(skill_files)
.chain(well_known_files)
diff --git a/tests/integration_tests/remove.rs b/tests/integration_tests/remove.rs
index d733e408b..88d39a047 100644
--- a/tests/integration_tests/remove.rs
+++ b/tests/integration_tests/remove.rs
@@ -2807,6 +2807,65 @@ fn restore_dir_permissions(dir: &std::path::Path) {
}
}
+// ============================================================================
+// Docs-page example snapshot
+//
+// See tests/integration_tests/merge.rs header comment for the docs-example
+// convention — `<!-- wt remove (docs-example) -->` in `src/cli/mod.rs`.
+// ============================================================================
+
+/// `wt remove` example for `docs/content/remove.md` — pre-remove hook running
+/// `flyctl scale count 0`, background cleanup.
+#[rstest]
+fn test_docs_remove_pre_remove_hook(mut repo: TestRepo) {
+ repo.run_git(&["config", "worktrunk.hints.worktree-path", "true"]);
+
+ let bin_dir = repo.root_path().join(".bin");
+ std::fs::create_dir_all(&bin_dir).unwrap();
+ crate::common::mock_commands::MockConfig::new("flyctl")
+ .command(
+ "scale",
+ crate::common::mock_commands::MockResponse::output("Scaling app to 0 machines\n"),
+ )
+ .write(&bin_dir);
+
+ repo.write_project_config(
+ r#"[[pre-remove]]
+cleanup = "flyctl scale count 0"
+"#,
+ );
+ repo.run_git(&["add", ".config", ".bin"]);
+ repo.run_git(&["commit", "-m", "Add project config"]);
+
+ let api_wt = repo.add_worktree("api");
+
+ let directive_file = repo
+ .root_path()
+ .parent()
+ .unwrap()
+ .join(".wt-directive-docs-remove");
+ std::fs::write(&directive_file, "").unwrap();
+
+ let mut paths: Vec<std::path::PathBuf> = std::env::var_os("PATH")
+ .map(|p| std::env::split_paths(&p).collect())
+ .unwrap_or_default();
+ paths.insert(0, bin_dir.clone());
+ let new_path = std::env::join_paths(&paths).unwrap();
+ let bin_dir_str = bin_dir.to_string_lossy().into_owned();
+ let directive_file_str = directive_file.to_string_lossy().into_owned();
+
+ let settings = setup_snapshot_settings(&repo);
+ settings.bind(|| {
+ assert_cmd_snapshot!("docs_remove_pre_remove_hook", {
+ let mut cmd = make_snapshot_cmd(&repo, "remove", &["--yes"], Some(&api_wt));
+ cmd.env("PATH", &new_path);
+ cmd.env("MOCK_CONFIG_DIR", &bin_dir_str);
+ cmd.env("WORKTRUNK_DIRECTIVE_CD_FILE", &directive_file_str);
+ cmd
+ });
+ });
+}
+
// ============================================================================
// --format=json
// ============================================================================
diff --git a/tests/integration_tests/user_hooks.rs b/tests/integration_tests/user_hooks.rs
index c685f9f89..8ea18eb71 100644
--- a/tests/integration_tests/user_hooks.rs
+++ b/tests/integration_tests/user_hooks.rs
@@ -3510,3 +3510,49 @@ approved-commands = ["echo project-hook"]
assert_cmd_snapshot!("hook_verbose_background_dedup", cmd);
});
}
+
+// ============================================================================
+// Docs-page example snapshot
+//
+// See tests/integration_tests/merge.rs header comment for the docs-example
+// convention — `<!-- wt hook pre-merge (docs-example) -->` in `src/cli/mod.rs`.
+// ============================================================================
+
+/// `wt hook pre-merge` example for `docs/content/hook.md` — two named
+/// pre-merge hooks (test, lint) running mocked `cargo` commands.
+#[rstest]
+fn test_docs_hook_pre_merge(repo: TestRepo) {
+ repo.run_git(&["config", "worktrunk.hints.worktree-path", "true"]);
+
+ let bin_dir = repo.root_path().join(".bin");
+ fs::create_dir_all(&bin_dir).unwrap();
+ crate::common::mock_commands::create_mock_cargo(&bin_dir);
+
+ repo.write_project_config(
+ r#"[[pre-merge]]
+test = "cargo test"
+
+[[pre-merge]]
+lint = "cargo clippy"
+"#,
+ );
+ repo.run_git(&["add", ".config", ".bin"]);
+ repo.run_git(&["commit", "-m", "Add project config"]);
+
+ let mut paths: Vec<std::path::PathBuf> = std::env::var_os("PATH")
+ .map(|p| std::env::split_paths(&p).collect())
+ .unwrap_or_default();
+ paths.insert(0, bin_dir.clone());
+ let new_path = std::env::join_paths(&paths).unwrap();
+ let bin_dir_str = bin_dir.to_string_lossy().into_owned();
+
+ let settings = setup_snapshot_settings(&repo);
+ settings.bind(|| {
+ assert_cmd_snapshot!("docs_hook_pre_merge", {
+ let mut cmd = make_snapshot_cmd(&repo, "hook", &["pre-merge", "--yes"], None);
+ cmd.env("PATH", &new_path);
+ cmd.env("MOCK_CONFIG_DIR", &bin_dir_str);
+ cmd
+ });
+ });
+}
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 317ce06fe..fe06fc41b 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -87,14 +87,37 @@ The table renders progressively: branch names, paths, and commit hashes appear i
List all worktrees:
  wt list
+   Branch Status HEAD± main↕ Remote⇅ Commit Age Message
+  @ feature-api + ↕⇡ +54 -5 ↑4 ↓1 ⇡3 6814f02a 30m Add API tests
+  ^ main ^⇅ ⇡1 ⇣1 41ee0834 4d Merge fix-auth: hardened to…
+  + fix-auth ↕| ↑2 ↓1 | b772e68b 5h Add secure token storage
+  + fix-typos _| | 41ee0834 4d Merge fix-auth: hardened to…
+  
+  ○ Showing 4 worktrees, 1 with changes, 2 ahead, 1 column hidden
Include CI status, line diffs, and LLM summaries:
  wt list --full
+   Branch Status HEAD± main↕ main…± Summary Remote⇅ CI Commit
+  @ feature-api + ↕⇡ +54 -5 ↑4 ↓1 +234 -24 Refactor API to REST architecture with middleware ⇡3 ● 6814f02a
+  ^ main ^⇅ ⇡1 ⇣1 ● 41ee0834
+  + fix-auth ↕| ↑2 ↓1 +25 -11 Harden auth with constant-time token validation | ● b772e68b
+  + fix-typos _| | ● 41ee0834
+  
+  ○ Showing 4 worktrees, 1 with changes, 2 ahead, 3 columns hidden
Include branches that don't have worktrees:
  wt list --branches --full
+   Branch Status HEAD± main↕ main…± Summary Remote⇅ CI Commit
+  @ feature-api + ↕⇡ +54 -5 ↑4 ↓1 +234 -24 Refactor API to REST architecture with middleware ⇡3 ● 6814f02a
+  ^ main ^⇅ ⇡1 ⇣1 ● 41ee0834
+  + fix-auth ↕| ↑2 ↓1 +25 -11 Harden auth with constant-time token validation | ● b772e68b
+  + fix-typos _| | ● 41ee0834
+   exp /↕ ↑2 ↓1 +137 Explore GraphQL schema and resolvers 96379229
+   wip /↕ ↑1 ↓1 +33 Start API documentation b40716dc
+  
+  ○ Showing 4 worktrees, 2 branches, 1 with changes, 4 ahead, 3 columns hidden
Output as JSON for scripting:
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 0b542915c..3b90b89bd 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
@@ -96,14 +96,53 @@ LLM-generated summaries of each branch's changes.
List all worktrees:
  wt list
+   Branch Status HEAD± main↕ Remote⇅ Commit Age Message
+  @ feature-api + ↕⇡ +54 -5 ↑4 ↓1 ⇡3 6814f02a 30m Add API 
+  tests
+  ^ main ^⇅ ⇡1 ⇣1 41ee0834 4d Merge 
+  fix-auth: hardened to…
+  + fix-auth ↕| ↑2 ↓1 | b772e68b 5h Add 
+  secure token storage
+  + fix-typos _| | 41ee0834 4d Merge 
+  fix-auth: hardened to…
+  
+  ○ Showing 4 worktrees, 1 with changes, 2 ahead, 1 column hidden
Include CI status, line diffs, and LLM summaries:
  wt list --full
+   Branch Status HEAD± main↕ main…± Summary 
+   Remote⇅ CI Commit
+  @ feature-api + ↕⇡ +54 -5 ↑4 ↓1 +234 -24 Refactor API to REST 
+  architecture with middleware ⇡3 ● 6814f02a
+  ^ main ^⇅ 
+   ⇡1 ⇣1 ● 41ee0834
+  + fix-auth ↕| ↑2 ↓1 +25 -11 Harden auth with 
+  constant-time token validation | ● b772e68b
+  + fix-typos _| 
+   | ● 41ee0834
+  
+  ○ Showing 4 worktrees, 1 with changes, 2 ahead, 3 columns hidden
Include branches that don't have worktrees:
  wt list --branches --full
+   Branch Status HEAD± main↕ main…± Summary 
+   Remote⇅ CI Commit
+  @ feature-api + ↕⇡ +54 -5 ↑4 ↓1 +234 -24 Refactor API to REST 
+  architecture with middleware ⇡3 ● 6814f02a
+  ^ main ^⇅ 
+   ⇡1 ⇣1 ● 41ee0834
+  + fix-auth ↕| ↑2 ↓1 +25 -11 Harden auth with 
+  constant-time token validation | ● b772e68b
+  + fix-typos _| 
+   | ● 41ee0834
+   exp /↕ ↑2 ↓1 +137 Explore GraphQL schema
+   and resolvers 96379229
+   wip /↕ ↑1 ↓1 +33 Start API 
+  documentation b40716dc
+  
+  ○ Showing 4 worktrees, 2 branches, 1 with changes, 4 ahead, 3 columns hidden
Output as JSON for scripting:
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 19009f863..bc0c6ada5 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
@@ -104,8 +104,20 @@ Unlike `git merge`, this merges the current branch into the target branch — no
Merge to the default branch:
+<!-- wt merge (docs-example) -->
```bash
$ wt merge
+◎ Running pre-merge project:test
+ cargo nextest run
+ Finished `test` profile [unoptimized + debuginfo] target(s) in 0.02s
+ Summary [ 0.002s] 2 tests run: 2 passed, 0 skipped
+◎ Merging 1 commit to main @ a1b2c3d (no commit/squash/rebase needed)
+ * a1b2c3d feat: add hook registration
+ hook.rs | 31 +++++++++++++++++++++++++++++++
+ 1 file changed, 31 insertions(+)
+✓ Merged to main (1 commit, 1 file, +31)
+◎ Removing hooks worktree & branch in background (same commit as main, _)
+○ Switched to worktree for main @ ~/repo
```
Merge to a different branch:
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 7238821df..519652e84 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -104,6 +104,17 @@ Unlike git merge, this merges the current branch into the target branch
Merge to the default branch:
  wt merge
+  ◎ Running pre-merge project:test
+   cargo nextest run
+   Finished `test` profile [unoptimized + debuginfo] target(s) in 0.02s
+   Summary [ 0.002s] 2 tests run: 2 passed, 0 skipped
+  ◎ Merging 1 commit to main @ a1b2c3d (no commit/squash/rebase needed)
+   * a1b2c3d feat: add hook registration
+   hook.rs | 31 +++++++++++++++++++++++++++++++
+   1 file changed, 31 insertions(+)
+  ✓ Merged to main (1 commit, 1 file, +31)
+  ◎ Removing hooks worktree & branch in background (same commit as main, _)
+  ○ Switched to worktree for main @ ~/repo
Merge to a different branch:
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 b363693b6..fe2285380 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -91,6 +91,11 @@ Usage: wt remove [OPTIONS] [BRANCHES]...
Remove current worktree:
  wt remove
+  ◎ Running pre-remove project:cleanup
+   flyctl scale count 0
+  Scaling app to 0 machines
+  ◎ Removing api worktree & branch in background (same commit as main, _)
+  ○ Switched to worktree for main @ ~/repo
Remove specific worktrees / branches:
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 6c53e70ec..6e51b9750 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -71,6 +71,9 @@ Usage: wt step [OPTIONS] <COMMAND>
Commit with LLM-generated message:
  wt step commit
+  ◎ Generating commit message and committing changes... (2 files, +26)
+   feat(validation): add input validation utilities
+  ✓ Committed changes @ a1b2c3d
Manual merge workflow with review between steps:
diff --git a/tests/snapshots/integration__integration_tests__merge__docs_merge_pre_merge_hook.snap b/tests/snapshots/integration__integration_tests__merge__docs_merge_pre_merge_hook.snap
new file mode 100644
index 000000000..f70410bb4
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__merge__docs_merge_pre_merge_hook.snap
@@ -0,0 +1,58 @@
+---
+source: tests/integration_tests/merge.rs
+info:
+ program: wt
+ args:
+ - merge
+ - "--yes"
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_DIRECTIVE_CD_FILE: "[DIRECTIVE_CD_FILE]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Running pre-merge project:test
+  cargo nextest run
+ Finished `test` profile [unoptimized + debuginfo] target(s) in 0.02s
+ Summary [ 0.002s] 2 tests run: 2 passed, 0 skipped
+◎ Merging 1 commit to main @ [HASH] (no commit/squash/rebase needed)
+  * [HASH] feat: add hook registration
+  hook.rs | 31 +++++++++++++++++++++++++++++++
+  1 file changed, 31 insertions(+)
+✓ Merged to main (1 commit, 1 file, +31)
+◎ Removing hooks worktree & branch in background (same commit as main, _)
+○ Switched to worktree for main @ _REPO_
diff --git a/tests/snapshots/integration__integration_tests__merge__docs_merge_squash_llm.snap b/tests/snapshots/integration__integration_tests__merge__docs_merge_squash_llm.snap
new file mode 100644
index 000000000..0a626c144
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__merge__docs_merge_squash_llm.snap
@@ -0,0 +1,65 @@
+---
+source: tests/integration_tests/merge.rs
+info:
+ program: wt
+ args:
+ - merge
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_COMMIT__GENERATION__COMMAND: "cat >/dev/null && echo 'feat(auth): Implement JWT authentication system\n\nAdd comprehensive JWT token handling including validation, refresh\nlogic, and authentication tests.'"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_DIRECTIVE_CD_FILE: "[DIRECTIVE_CD_FILE]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Squashing 3 commits into a single commit (5 files, +16)...
+◎ Generating squash commit message...
+  feat(auth): Implement JWT authentication system
+ 
+  Add comprehensive JWT token handling including validation, refresh
+  logic, and authentication tests.
+✓ Squashed @ [HASH]
+◎ Merging 1 commit to main @ [HASH] (no rebase needed)
+  * [HASH] feat(auth): Implement JWT authentication system
+  auth.rs | 2 ++
+  auth_test.rs | 2 ++
+  integration_test.rs | 6 ++++++
+  jwt.rs | 3 +++
+  jwt_test.rs | 3 +++
+  5 files changed, 16 insertions(+)
+✓ Merged to main (1 commit, 5 files, +16)
+◎ Removing feature worktree & branch in background (same commit as main, _)
+○ Switched to worktree for main @ _REPO_
diff --git a/tests/snapshots/integration__integration_tests__merge__docs_step_commit_llm.snap b/tests/snapshots/integration__integration_tests__merge__docs_step_commit_llm.snap
new file mode 100644
index 000000000..e9f514cf0
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__merge__docs_step_commit_llm.snap
@@ -0,0 +1,50 @@
+---
+source: tests/integration_tests/merge.rs
+info:
+ program: wt
+ args:
+ - step
+ - commit
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_COMMIT__GENERATION__COMMAND: "cat >/dev/null && echo 'feat(validation): add input validation utilities'"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Generating commit message and committing changes... (2 files, +26)
+  feat(validation): add input validation utilities
+✓ Committed changes @ [HASH]
diff --git a/tests/snapshots/integration__integration_tests__merge__docs_step_squash_llm.snap b/tests/snapshots/integration__integration_tests__merge__docs_step_squash_llm.snap
new file mode 100644
index 000000000..4262a675b
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__merge__docs_step_squash_llm.snap
@@ -0,0 +1,54 @@
+---
+source: tests/integration_tests/merge.rs
+info:
+ program: wt
+ args:
+ - step
+ - squash
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_COMMIT__GENERATION__COMMAND: "cat >/dev/null && echo 'feat(auth): Implement JWT authentication system\n\nAdd comprehensive JWT token handling including validation, refresh\nlogic, and authentication tests.'"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Squashing 3 commits into a single commit (5 files, +16)...
+◎ Generating squash commit message...
+  feat(auth): Implement JWT authentication system
+ 
+  Add comprehensive JWT token handling including validation, refresh
+  logic, and authentication tests.
+✓ Squashed @ [HASH]
diff --git a/tests/snapshots/integration__integration_tests__remove__docs_remove_pre_remove_hook.snap b/tests/snapshots/integration__integration_tests__remove__docs_remove_pre_remove_hook.snap
new file mode 100644
index 000000000..1086bcbfa
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__remove__docs_remove_pre_remove_hook.snap
@@ -0,0 +1,52 @@
+---
+source: tests/integration_tests/remove.rs
+info:
+ program: wt
+ args:
+ - remove
+ - "--yes"
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_DIRECTIVE_CD_FILE: "[DIRECTIVE_CD_FILE]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Running pre-remove project:cleanup
+  flyctl scale count 0
+Scaling app to 0 machines
+◎ Removing api worktree & branch in background (same commit as main, _)
+○ Switched to worktree for main @ _REPO_
diff --git a/tests/snapshots/integration__integration_tests__user_hooks__docs_hook_pre_merge.snap b/tests/snapshots/integration__integration_tests__user_hooks__docs_hook_pre_merge.snap
new file mode 100644
index 000000000..628ee115f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__user_hooks__docs_hook_pre_merge.snap
@@ -0,0 +1,63 @@
+---
+source: tests/integration_tests/user_hooks.rs
+info:
+ program: wt
+ args:
+ - hook
+ - pre-merge
+ - "--yes"
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Running pre-merge project:test
+  cargo test
+ Finished test [unoptimized + debuginfo] target(s) in 0.12s
+ Running unittests src/lib.rs (target/debug/deps/worktrunk-abc123)
+
+running 18 tests
+test auth::tests::test_jwt_decode ... ok
+test auth::tests::test_jwt_encode ... ok
+test auth::tests::test_token_refresh ... ok
+test auth::tests::test_token_validation ... ok
+
+test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.08s
+◎ Running pre-merge project:lint
+  cargo clippy
+ Checking worktrunk v0.1.0
+ Finished dev [unoptimized + debuginfo] target(s) in 1.23s