Skip to content

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

docs: add Quick Start section to front page (#851)

Maximilian Roos69b3e475095e
diff --git a/.claude-plugin/skills/worktrunk/reference/claude-code.md b/.claude-plugin/skills/worktrunk/reference/claude-code.md
index 8b5c2e8f2..f692bf812 100644
--- a/.claude-plugin/skills/worktrunk/reference/claude-code.md
+++ b/.claude-plugin/skills/worktrunk/reference/claude-code.md
@@ -27,7 +27,7 @@ Claude Code is designed to load the skill automatically when it detects worktrun
The plugin tracks Claude sessions with status markers in `wt list`:
-<span class="prompt">$</span> <span class="cmd">wt list</span>
+<span class="cmd">wt list</span>
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Path</b> <b>Remote⇅</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>
+ feature-api <span class=d>↑</span> 🤖 <span class=g>↑1</span> ../repo.feature-api <span class=d>70343f03</span> <span class=d>1d</span> <span class=d>Add REST API endpoints</span>
diff --git a/.claude-plugin/skills/worktrunk/reference/list.md b/.claude-plugin/skills/worktrunk/reference/list.md
index ade6c92ab..428e259b6 100644
--- a/.claude-plugin/skills/worktrunk/reference/list.md
+++ b/.claude-plugin/skills/worktrunk/reference/list.md
@@ -10,7 +10,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i
List all worktrees:
-<span class="prompt">$</span> <span class="cmd">wt list</span>
+<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-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>
@@ -20,7 +20,7 @@ List all worktrees:
Include CI status and line diffs:
-<span class="prompt">$</span> <span class="cmd">wt list --full</span>
+<span class="cmd">wt list --full</span>
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Remote⇅</b> <b>CI</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>+234</span> <span class=r>-24</span> <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></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=g>●</span> <span class=d>41ee0834</span> <span class=d>4d</span> <span class=d>Merge fix-au…</span>
@@ -30,7 +30,7 @@ Include CI status and line diffs:
Include branches that don't have worktrees:
-<span class="prompt">$</span> <span class="cmd">wt list --branches --full</span>
+<span class="cmd">wt list --branches --full</span>
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Remote⇅</b> <b>CI</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>+234</span> <span class=r>-24</span> <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></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=g>●</span> <span class=d>41ee0834</span> <span class=d>4d</span> <span class=d>Merge fix-au…</span>
diff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
index b1f742474..108ed5ed9 100644
--- a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
+++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
@@ -43,7 +43,7 @@ server = "lsof -ti :{{ branch | hash_port }} | xargs kill 2>/dev/null || true"
The URL column in `wt list` shows each worktree's dev server:
-<span class="prompt">$</span> <span class="cmd">wt list</span>
+<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>
+ 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>http://localhost:10703</span> <span class=d>6814f02a</span> <span class=d>30m</span>
diff --git a/.claude-plugin/skills/worktrunk/reference/worktrunk.md b/.claude-plugin/skills/worktrunk/reference/worktrunk.md
index 5cacfddd7..f67d9a5ed 100644
--- a/.claude-plugin/skills/worktrunk/reference/worktrunk.md
+++ b/.claude-plugin/skills/worktrunk/reference/worktrunk.md
@@ -111,6 +111,59 @@ Alternatively, disable Windows Terminal's alias (Settings → Privacy & security
paru worktrunk-bin && wt config shell install
```
+## Quick start
+
+Create a worktree for a new feature:
+
+<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>
+
+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/):
+
+<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>+53</span> <span class=d>0e631add</span> <span class=d>1d</span> <span class=d>Initial commit</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 column hidden</span>
+
+The `@` marks the current worktree. `+` means uncommitted changes, `↕` means unpushed commits.
+
+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
+```
+
+**Local merge** — squash, rebase onto main, fast-forward merge, clean up:
+
+<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>
+<span class=g>✓</span> <span class=g>Committed changes @ <span class=d>a1b2c3d</span></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> Add authentication module
+<span style='background:var(--bright-white,#fff)'> </span> auth.rs | 51 <span class=g>+++++++++++++++++++++++++++++++++++++++++++++++++++</span>
+<span style='background:var(--bright-white,#fff)'> </span> lib.rs | 2 <span class=g>++</span>
+<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>◎ 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>
+
+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'
+```
+
+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).
+
## Next steps
- Learn the core commands: [`wt switch`](https://worktrunk.dev/switch/), [`wt list`](https://worktrunk.dev/list/), [`wt merge`](https://worktrunk.dev/merge/), [`wt remove`](https://worktrunk.dev/remove/)
diff --git a/README.md b/README.md
index 954999fc5..45dcc29d3 100644
--- a/README.md
+++ b/README.md
@@ -131,6 +131,68 @@ Alternatively, disable Windows Terminal's alias (Settings → Privacy & security
paru worktrunk-bin && wt config shell install
```
+## Quick start
+
+Create a worktree for a new feature:
+
+```console
+wt switch --create feature-auth
+✓ Created branch feature-auth from main and worktree @ repo.feature-auth
+
+```
+
+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/):
+
+```console
+wt list
+ Branch Status HEAD± main↕ Remote⇅ Commit Age Message
+@ feature-auth + – +53 0e631add 1d Initial commit
+^ main ^⇡ ⇡1 0e631add 1d Initial commit
+
+○ Showing 2 worktrees, 1 with changes, 1 column hidden
+
+```
+
+The `@` marks the current worktree. `+` means uncommitted changes, `↕` means unpushed commits.
+
+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
+```
+
+**Local merge** — squash, rebase onto main, fast-forward merge, clean up:
+
+```console
+wt merge main
+◎ Generating commit message and committing changes... (2 files, +53, no squashing needed)
+ Add authentication module
+✓ Committed changes @ a1b2c3d
+◎ Merging 1 commit to main @ a1b2c3d (no rebase needed)
+ * a1b2c3d Add authentication module
+ auth.rs | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
+ lib.rs | 2 ++
+ 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
+
+```
+
+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'
+```
+
+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).
+
## Next steps
- Learn the core commands: [`wt switch`](https://worktrunk.dev/switch/), [`wt list`](https://worktrunk.dev/list/), [`wt merge`](https://worktrunk.dev/merge/), [`wt remove`](https://worktrunk.dev/remove/)
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.md
index 3acc73274..7c0378c2f 100644
--- a/docs/content/claude-code.md
+++ b/docs/content/claude-code.md
@@ -36,7 +36,7 @@ The plugin tracks Claude sessions with status markers in `wt list`:
<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__list_with_user_marker.snap — edit source to update -->
{% terminal() %}
-<span class="prompt">$</span> <span class="cmd">wt list</span>
+<span class="cmd">wt list</span>
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Path</b> <b>Remote⇅</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>
+ feature-api <span class=d>↑</span> 🤖 <span class=g>↑1</span> ../repo.feature-api <span class=d>70343f03</span> <span class=d>1d</span> <span class=d>Add REST API endpoints</span>
diff --git a/docs/content/list.md b/docs/content/list.md
index cd0b0e2ff..4e490458d 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -28,7 +28,7 @@ List all worktrees:
<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_list.snap — edit source to update -->
{% terminal() %}
-<span class="prompt">$</span> <span class="cmd">wt list</span>
+<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-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>
@@ -44,7 +44,7 @@ Include CI status and line diffs:
<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_list_full.snap — edit source to update -->
{% terminal() %}
-<span class="prompt">$</span> <span class="cmd">wt list --full</span>
+<span class="cmd">wt list --full</span>
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Remote⇅</b> <b>CI</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>+234</span> <span class=r>-24</span> <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></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=g>●</span> <span class=d>41ee0834</span> <span class=d>4d</span> <span class=d>Merge fix-au…</span>
@@ -60,7 +60,7 @@ 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() %}
-<span class="prompt">$</span> <span class="cmd">wt list --branches --full</span>
+<span class="cmd">wt list --branches --full</span>
<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Remote⇅</b> <b>CI</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>+234</span> <span class=r>-24</span> <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></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=g>●</span> <span class=d>41ee0834</span> <span class=d>4d</span> <span class=d>Merge fix-au…</span>
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index bf5a6c7bd..38e9ddcfe 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -52,7 +52,7 @@ The URL column in `wt list` shows each worktree's dev server:
<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__tips_dev_server_workflow.snap — edit source to update -->
{% terminal() %}
-<span class="prompt">$</span> <span class="cmd">wt list</span>
+<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>
+ 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>http://localhost:10703</span> <span class=d>6814f02a</span> <span class=d>30m</span>
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index 275274963..3afa888da 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -130,6 +130,77 @@ Alternatively, disable Windows Terminal's alias (Settings → Privacy & security
paru worktrunk-bin && wt config shell install
```
+## Quick start
+
+Create a worktree for a new feature:
+
+<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__quickstart_switch.snap — edit source to update -->
+
+{% terminal() %}
+<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 %}
+
+<!-- END AUTO-GENERATED -->
+
+This creates a new branch and worktree, then switches to it. Do your work, then check all worktrees with [`wt list`](@/list.md):
+
+<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__quickstart_list.snap — edit source to update -->
+
+{% terminal() %}
+<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>+53</span> <span class=d>0e631add</span> <span class=d>1d</span> <span class=d>Initial commit</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 column hidden</span>
+{% end %}
+
+<!-- END AUTO-GENERATED -->
+
+The `@` marks the current worktree. `+` means uncommitted changes, `↕` means unpushed commits.
+
+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
+```
+
+**Local merge** — squash, rebase onto main, fast-forward merge, clean up:
+
+<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__quickstart_merge.snap — edit source to update -->
+
+{% terminal() %}
+<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>
+<span class=g>✓</span> <span class=g>Committed changes @ <span class=d>a1b2c3d</span></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> Add authentication module
+<span style='background:var(--bright-white,#fff)'> </span> auth.rs | 51 <span class=g>+++++++++++++++++++++++++++++++++++++++++++++++++++</span>
+<span style='background:var(--bright-white,#fff)'> </span> lib.rs | 2 <span class=g>++</span>
+<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>◎ 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 %}
+
+<!-- END AUTO-GENERATED -->
+
+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'
+```
+
+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).
+
## Next steps
- Learn the core commands: [`wt switch`](@/switch.md), [`wt list`](@/list.md), [`wt merge`](@/merge.md), [`wt remove`](@/remove.md)
diff --git a/docs/sass/custom.scss b/docs/sass/custom.scss
index 75688b6ac..8b8415f2d 100644
--- a/docs/sass/custom.scss
+++ b/docs/sass/custom.scss
@@ -543,14 +543,17 @@ main {
line-height: 1.5;
color: var(--wt-color-text); // Default text color for terminal (not syntax-highlighted)
- .prompt {
- color: var(--wt-color-text-soft);
- }
-
- // Command text after prompt - bold amber for visibility
+ // Command text - bold amber for visibility
+ // Prompt ($) is generated via ::before, making it non-copyable
.cmd {
color: var(--wt-color-accent);
font-weight: 600;
+
+ &::before {
+ content: "$ ";
+ color: var(--wt-color-text-soft);
+ font-weight: 400;
+ }
}
// Softer bold for table headers and branch names
diff --git a/tests/common/mock_commands.rs b/tests/common/mock_commands.rs
index aacaa8125..6b0384449 100644
--- a/tests/common/mock_commands.rs
+++ b/tests/common/mock_commands.rs
@@ -283,6 +283,17 @@ Includes comprehensive test coverage and input validation.",
.write(bin_dir);
}
+/// Create a mock llm command for quickstart documentation.
+/// Simple output for clean documentation examples.
+pub fn create_mock_llm_quickstart(bin_dir: &Path) {
+ MockConfig::new("llm")
+ .command(
+ "_default",
+ MockResponse::output("Add authentication module"),
+ )
+ .write(bin_dir);
+}
+
/// Create a mock uv command for dependency sync and dev server.
pub fn create_mock_uv_sync(bin_dir: &Path) {
MockConfig::new("uv")
diff --git a/tests/integration_tests/list.rs b/tests/integration_tests/list.rs
index 2f8cad6e3..383753da6 100644
--- a/tests/integration_tests/list.rs
+++ b/tests/integration_tests/list.rs
@@ -1,7 +1,9 @@
use crate::common::{
- DAY, HOUR, MINUTE, TestRepo, list_snapshots, repo, repo_with_remote, wt_command,
+ DAY, HOUR, MINUTE, TestRepo, list_snapshots, make_snapshot_cmd,
+ mock_commands::create_mock_llm_quickstart, repo, repo_with_remote, wt_command,
};
use insta_cmd::assert_cmd_snapshot;
+use path_slash::PathExt as _;
use rstest::rstest;
/// Creates worktrees with specific timestamps for ordering tests.
@@ -756,6 +758,175 @@ fn test_list_user_marker_with_special_characters(mut repo: TestRepo) {
assert_cmd_snapshot!(list_snapshots::command(&repo, repo.root_path()));
}
+// =============================================================================
+// Quick Start Examples
+// =============================================================================
+//
+// These functions create minimal repos for Quick Start documentation.
+// The examples show the simplest workflow: create → list → merge.
+
+/// Remove fixture worktrees to start with a clean main-only repo.
+///
+/// The standard TestRepo fixture includes feature-a, feature-b, feature-c.
+/// Doc examples need clean output without these.
+fn remove_fixture_worktrees(repo: &mut TestRepo) {
+ for branch in &["feature-a", "feature-b", "feature-c"] {
+ let worktree_path = repo
+ .root_path()
+ .parent()
+ .unwrap()
+ .join(format!("repo.{}", branch));
+ if worktree_path.exists() {
+ let _ = repo
+ .git_command()
+ .args([
+ "worktree",
+ "remove",
+ "--force",
+ worktree_path.to_str().unwrap(),
+ ])
+ .output();
+ }
+ let _ = repo.git_command().args(["branch", "-D", branch]).output();
+ }
+}
+
+/// Set up a minimal repo with just main branch.
+///
+/// Creates a simple codebase:
+/// - README.md with project description
+/// - lib.rs with a simple function
+/// - Remote configured and pushed
+///
+/// Used as base for both Quick Start and full README examples.
+fn setup_quickstart_base(repo: &mut TestRepo) {
+ remove_fixture_worktrees(repo);
+
+ // Suppress the "customize worktree locations" hint for clean snapshots
+ repo.run_git(&["config", "worktrunk.hints.worktree-path", "true"]);
+
+ // Simple README
+ std::fs::write(
+ repo.root_path().join("README.md"),
+ "# My Project\n\nA Rust application.\n",
+ )
+ .unwrap();
+
+ // Simple lib.rs
+ std::fs::write(
+ repo.root_path().join("lib.rs"),
+ r#"/// Adds two numbers.
+pub fn add(a: i32, b: i32) -> i32 {
+ a + b
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_add() {
+ assert_eq!(add(2, 3), 5);
+ }
+}
+"#,
+ )
+ .unwrap();
+
+ repo.run_git(&["add", "README.md", "lib.rs"]);
+ repo.commit_staged_with_age("Initial commit", DAY, repo.root_path());
+ repo.setup_remote("main");
+}
+
+/// Set up a Quick Start example repo with main + feature-auth.
+///
+/// Creates a simple scenario:
+/// - main: Initial codebase
+/// - feature-auth: Uncommitted changes adding authentication (WIP state)
+///
+/// Returns the feature-auth worktree path.
+fn setup_quickstart_repo(repo: &mut TestRepo) -> std::path::PathBuf {
+ setup_quickstart_base(repo);
+
+ // Create feature-auth worktree
+ let feature_auth = repo.add_worktree("feature-auth");
+
+ // Add authentication module (not committed - realistic WIP state)
+ std::fs::write(
+ feature_auth.join("auth.rs"),
+ r#"//! Authentication module for user session management.
+
+use std::time::{Duration, SystemTime};
+
+/// A user session with token and expiry.
+pub struct Session {
+ token: String,
+ expires_at: SystemTime,
+}
+
+impl Session {
+ /// Creates a new session with the given token and TTL.
+ pub fn new(token: String, ttl: Duration) -> Self {
+ Self {
+ token,
+ expires_at: SystemTime::now() + ttl,
+ }
+ }
+
+ /// Returns true if the session has not expired.
+ pub fn is_valid(&self) -> bool {
+ SystemTime::now() < self.expires_at
+ }
+
+ /// Validates the token format.
+ pub fn validate_token(token: &str) -> bool {
+ token.len() >= 32 && token.chars().all(|c| c.is_ascii_alphanumeric())
+ }
+}
+
+/// Checks if user is authenticated with a valid session.
+pub fn is_authenticated(session: Option<&Session>) -> bool {
+ session.map(|s| s.is_valid()).unwrap_or(false)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_session_validity() {
+ let session = Session::new("a".repeat(32), Duration::from_secs(3600));
+ assert!(session.is_valid());
+ }
+
+ #[test]
+ fn test_validate_token() {
+ assert!(!Session::validate_token("short"));
+ assert!(Session::validate_token(&"x".repeat(32)));
+ }
+}
+"#,
+ )
+ .unwrap();
+
+ // Update lib.rs to include the new module
+ let lib_content = std::fs::read_to_string(feature_auth.join("lib.rs")).unwrap();
+ std::fs::write(
+ feature_auth.join("lib.rs"),
+ format!("mod auth;\n\n{}", lib_content),
+ )
+ .unwrap();
+
+ // Stage all changes (but don't commit - WIP state for wt list demo)
+ repo.run_git_in(&feature_auth, &["add", "auth.rs", "lib.rs"]);
+
+ feature_auth
+}
+
+// =============================================================================
+// Full README Examples
+// =============================================================================
+
/// Set up a repo for README examples showing realistic worktree states.
///
/// **Project context**: API modernization — migrating from legacy handlers to REST,
@@ -800,28 +971,8 @@ fn test_list_user_marker_with_special_characters(mut repo: TestRepo) {
/// to produce clean output for README/docs. If you need the fixture worktrees,
/// use a different setup function.
fn setup_readme_example_repo(repo: &mut TestRepo) -> std::path::PathBuf {
- // Remove fixture worktrees to produce clean doc output
- // These doc tests are used to generate README and website examples
- for branch in &["feature-a", "feature-b", "feature-c"] {
- let worktree_path = repo
- .root_path()
- .parent()
- .unwrap()
- .join(format!("repo.{}", branch));
- if worktree_path.exists() {
- let _ = repo
- .git_command()
- .args([
- "worktree",
- "remove",
- "--force",
- worktree_path.to_str().unwrap(),
- ])
- .output();
- }
- // Delete the branch after removing the worktree
- let _ = repo.git_command().args(["branch", "-D", branch]).output();
- }
+ // Start with clean base (removes fixture worktrees)
+ remove_fixture_worktrees(repo);
// === Set up main branch with initial codebase ===
// Main has a working API with security issues that fix-auth will harden
@@ -1623,6 +1774,168 @@ fn mock_ci_status(repo: &TestRepo, branch: &str, status: &str, source: &str, is_
std::fs::write(&cache_file, &cache_json).unwrap();
}
+// =============================================================================
+// Quick Start Snapshot Tests
+// =============================================================================
+
+/// Generate Quick Start example: `wt switch --create feature-auth` output
+///
+/// Shows the switch output when creating a new worktree from main.
+/// Sets WORKTRUNK_DIRECTIVE_FILE to simulate shell integration being active,
+/// which suppresses the "Cannot change directory" warning.
+/// Output: tests/snapshots/integration__integration_tests__list__quickstart_switch.snap
+#[rstest]
+fn test_quickstart_switch(mut repo: TestRepo) {
+ setup_quickstart_base(&mut repo);
+ // Create a temp file for the directive outside the repo to avoid making main dirty
+ let directive_file = repo
+ .root_path()
+ .parent()
+ .unwrap()
+ .join(".wt-directive-temp");
+ std::fs::write(&directive_file, "").unwrap();
+ assert_cmd_snapshot!("quickstart_switch", {
+ let mut cmd = make_snapshot_cmd(&repo, "switch", &["--create", "feature-auth"], None);
+ cmd.env("WORKTRUNK_DIRECTIVE_FILE", &directive_file);
+ cmd
+ });
+}
+
+/// Generate Quick Start example: Simple `wt list` output
+///
+/// Shows minimal 2-worktree scenario: main + feature-auth.
+/// Output: tests/snapshots/integration__integration_tests__list__quickstart_list.snap
+#[rstest]
+fn test_quickstart_list(mut repo: TestRepo) {
+ let feature_auth = setup_quickstart_repo(&mut repo);
+ assert_cmd_snapshot!(
+ "quickstart_list",
+ list_snapshots::command_readme(&repo, &feature_auth)
+ );
+}
+
+/// Generate Quick Start example: `wt merge` output
+///
+/// Shows merge output when merging feature-auth into main.
+/// Sets WORKTRUNK_DIRECTIVE_FILE to simulate shell integration being active,
+/// which suppresses the "Cannot change directory" warning.
+/// Output: tests/snapshots/integration__integration_tests__list__quickstart_merge.snap
+#[rstest]
+fn test_quickstart_merge(mut repo: TestRepo) {
+ setup_quickstart_base(&mut repo);
+
+ // Ensure main worktree is completely clean (no staged or unstaged changes)
+ repo.run_git(&["checkout", "--", "."]);
+ repo.run_git(&["clean", "-fd"]);
+
+ // Create feature-auth worktree with one commit
+ let feature_auth = repo.add_worktree("feature-auth");
+
+ // Add authentication module (same as setup_quickstart_repo)
+ std::fs::write(
+ feature_auth.join("auth.rs"),
+ r#"//! Authentication module for user session management.
+
+use std::time::{Duration, SystemTime};
+
+/// A user session with token and expiry.
+pub struct Session {
+ token: String,
+ expires_at: SystemTime,
+}
+
+impl Session {
+ /// Creates a new session with the given token and TTL.
+ pub fn new(token: String, ttl: Duration) -> Self {
+ Self {
+ token,
+ expires_at: SystemTime::now() + ttl,
+ }
+ }
+
+ /// Returns true if the session has not expired.
+ pub fn is_valid(&self) -> bool {
+ SystemTime::now() < self.expires_at
+ }
+
+ /// Validates the token format.
+ pub fn validate_token(token: &str) -> bool {
+ token.len() >= 32 && token.chars().all(|c| c.is_ascii_alphanumeric())
+ }
+}
+
+/// Checks if user is authenticated with a valid session.
+pub fn is_authenticated(session: Option<&Session>) -> bool {
+ session.map(|s| s.is_valid()).unwrap_or(false)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_session_validity() {
+ let session = Session::new("a".repeat(32), Duration::from_secs(3600));
+ assert!(session.is_valid());
+ }
+
+ #[test]
+ fn test_validate_token() {
+ assert!(!Session::validate_token("short"));
+ assert!(Session::validate_token(&"x".repeat(32)));
+ }
+}
+"#,
+ )
+ .unwrap();
+
+ // Update lib.rs to include the new module
+ let lib_content = std::fs::read_to_string(feature_auth.join("lib.rs")).unwrap();
+ std::fs::write(
+ feature_auth.join("lib.rs"),
+ format!("mod auth;\n\n{}", lib_content),
+ )
+ .unwrap();
+
+ // Stage files but don't commit - let wt merge do the committing
+ repo.run_git_in(&feature_auth, &["add", "auth.rs", "lib.rs"]);
+
+ // Create a temp file for the directive outside the repo to avoid making main dirty
+ let directive_file = repo
+ .root_path()
+ .parent()
+ .unwrap()
+ .join(".wt-directive-temp");
+ std::fs::write(&directive_file, "").unwrap();
+
+ // Create a cross-platform mock LLM command (uses mock-stub binary system)
+ // The mock-bin directory is already created by setup_mock_gh() via the repo fixture
+ let mock_bin_dir = repo.root_path().parent().unwrap().join("mock-bin");
+ create_mock_llm_quickstart(&mock_bin_dir);
+
+ // Configure the LLM path (Windows needs .exe extension)
+ let llm_name = if cfg!(windows) { "llm.exe" } else { "llm" };
+ let llm_path = mock_bin_dir.join(llm_name);
+
+ // Merge feature-auth into main
+ assert_cmd_snapshot!("quickstart_merge", {
+ let mut cmd = make_snapshot_cmd(&repo, "merge", &["main"], Some(&feature_auth));
+ cmd.env("WORKTRUNK_DIRECTIVE_FILE", &directive_file);
+ // Set MOCK_CONFIG_DIR so mock-stub can find llm.json
+ cmd.env("MOCK_CONFIG_DIR", &mock_bin_dir);
+ // Use to_slash_lossy() for Windows compatibility - bash can't handle backslash paths
+ cmd.env(
+ "WORKTRUNK_COMMIT__GENERATION__COMMAND",
+ llm_path.to_slash_lossy().as_ref(),
+ );
+ cmd
+ });
+}
+
+// =============================================================================
+// Full README Snapshot Tests
+// =============================================================================
+
/// Generate README example: Basic `wt list` output
///
/// Shows worktree states with status symbols, divergence, and remote tracking.
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index ff19a3c8e..4f032e3b4 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -64,6 +64,11 @@ static TMPDIR_MAIN_REGEX: LazyLock<Regex> =
/// Regex for REPO placeholder
static REPO_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\[REPO\]").unwrap());
+/// Regex for _REPO_ placeholder (used in insta-cmd snapshots)
+/// Matches _REPO_ followed by optional .branch suffix
+static REPO_UNDERSCORE_REGEX: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r"_REPO_(\.([a-zA-Z0-9_-]+))?").unwrap());
+
/// Regex to extract user config section from src/cli/mod.rs
/// Matches content between USER_CONFIG_START and USER_CONFIG_END markers
static USER_CONFIG_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
@@ -213,18 +218,68 @@ fn extract_section(content: &str, start_marker: &str, end_marker: &str) -> Strin
}
}
+/// Extract command line from snapshot YAML header
+///
+/// Parses the YAML front matter to extract program and args, returning the command line.
+/// Returns None if the snapshot doesn't have command info (e.g., non-insta_cmd snapshots).
+fn extract_command_from_snapshot(content: &str) -> Option<String> {
+ // Extract YAML front matter
+ if !content.starts_with("---") {
+ return None;
+ }
+ let parts: Vec<&str> = content.splitn(3, "---").collect();
+ if parts.len() < 3 {
+ return None;
+ }
+ let yaml = parts[1];
+
+ // Extract program (line: " program: wt")
+ let program = yaml
+ .lines()
+ .find(|l| l.trim().starts_with("program:"))
+ .map(|l| l.trim().strip_prefix("program:").unwrap().trim())?;
+
+ // Extract args (lines: " args:\n - switch\n - --create\n - feature")
+ let args_start = yaml.find("args:")?;
+ let args_section = &yaml[args_start..];
+ let args: Vec<&str> = args_section
+ .lines()
+ .skip(1) // Skip "args:" line
+ .take_while(|l| l.trim().starts_with("- "))
+ .map(|l| l.trim().strip_prefix("- ").unwrap().trim_matches('"'))
+ .collect();
+
+ if args.is_empty() {
+ Some(program.to_string())
+ } else {
+ Some(format!("{} {}", program, args.join(" ")))
+ }
+}
+
/// Replace test placeholders with display-friendly values
///
/// Transforms:
/// - `[HASH]` → `a1b2c3d`
/// - `[TMPDIR]/repo.branch` → `../repo.branch`
/// - `[TMPDIR]/repo` → `../repo`
-/// - `_REPO_` → `../repo`
+/// - `[REPO]` → `../repo`
+/// - `_REPO_` → `repo` (just the repo name, no path)
+/// - `_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");
- REPO_REGEX.replace_all(&content, "../repo").into_owned()
+ let content = REPO_REGEX.replace_all(&content, "../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())
+ } else {
+ "repo".to_string()
+ }
+ })
+ .into_owned()
}
/// Format replacement content based on output format
@@ -359,10 +414,11 @@ fn expand_command_placeholders(content: &str, snapshots_dir: &Path) -> Result<St
let normalized = trim_lines(&html);
// Build the terminal shortcode with standard template markers
+ // Prompt ($) is added via CSS ::before, so not included in HTML
let replacement = format!(
"<!-- ⚠️ AUTO-GENERATED from tests/snapshots/{} — edit source to update -->\n\n\
{{% terminal() %}}\n\
- <span class=\"prompt\">$</span> <span class=\"cmd\">{}</span>\n\
+ <span class=\"cmd\">{}</span>\n\
{}\n\
{{% end %}}\n\n\
<!-- END AUTO-GENERATED -->",
@@ -678,6 +734,30 @@ fn heading_to_anchor(heading: &str) -> String {
.join("-")
}
+/// Regex to match terminal shortcodes with AUTO-GENERATED-HTML markers
+/// Optionally captures a preceding bash code block (which becomes redundant)
+/// These need to be converted to plain code blocks for README
+static TERMINAL_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
+ Regex::new(
+ r"(?s)(?:```bash\n[^\n]+\n```\n+)?<!-- ⚠️ AUTO-GENERATED-HTML from [^\n]+ -->\n+\{% terminal\(\) %\}\n(.*?)\{% end %\}\n+<!-- END AUTO-GENERATED -->",
+ )
+ .unwrap()
+});
+
+/// Strip HTML tags from content
+fn strip_html(content: &str) -> String {
+ // Simple HTML tag stripping - handles most common cases
+ let tag_pattern = Regex::new(r"<[^>]+>").unwrap();
+ let result = tag_pattern.replace_all(content, "");
+ // Decode HTML entities
+ result
+ .replace("&amp;", "&")
+ .replace("&lt;", "<")
+ .replace("&gt;", ">")
+ .replace("&quot;", "\"")
+ .replace("&#39;", "'")
+}
+
/// Transform Zola-flavored markdown to GitHub-flavored markdown
///
/// Converts:
@@ -685,6 +765,7 @@ fn heading_to_anchor(heading: &str) -> String {
/// - `[text](@/page.md#anchor)` → `[text](https://worktrunk.dev/page/#anchor)`
/// - `{% rawcode() %}...{% end %}` → `<pre>...</pre>`
/// - `<figure class="demo">...<img src="/assets/X.gif"...>...</figure>` → `![alt](raw.githubusercontent.com/.../X.gif)`
+/// - AUTO-GENERATED-HTML terminal markers → plain code blocks
fn transform_zola_to_github(content: &str) -> String {
// Transform internal links
let content = ZOLA_LINK_PATTERN
@@ -704,6 +785,16 @@ fn transform_zola_to_github(content: &str) -> String {
})
.into_owned();
+ // Transform terminal markers to console code blocks for README
+ let content = TERMINAL_MARKER_PATTERN
+ .replace_all(&content, |caps: &regex::Captures| {
+ let inner = caps.get(1).unwrap().as_str();
+ // Strip HTML and extract command + output as single block
+ let plain = strip_html(inner);
+ format!("```console\n{}\n```", plain)
+ })
+ .into_owned();
+
// Transform figure/picture elements to markdown images with GitHub raw URLs
ZOLA_FIGURE_PATTERN
.replace_all(&content, |caps: &regex::Captures| {
@@ -1132,34 +1223,22 @@ fn sync_docs_snapshots(doc_path: &Path, project_root: &Path) -> Result<usize, Ve
&content,
&DOCS_SNAPSHOT_MARKER_PATTERN,
OutputFormat::DocsHtml,
- |snap_path, current_content| {
- // Extract existing command line from docs if present
- let existing_command = current_content
- .lines()
- .find(|line| line.contains("class=\"prompt\""))
- .map(|line| {
- // Convert HTML command back to plain text for matching
- // <span class="prompt">$</span> wt switch ... -> $ wt switch ...
- let plain = strip_html_tags(line);
- plain.trim().to_string()
- });
-
+ |snap_path, _current_content| {
let full_path = project_root_for_snapshots.join(snap_path);
let raw = fs::read_to_string(&full_path)
.map_err(|e| format!("Failed to read {}: {}", full_path.display(), e))?;
+
+ // Extract command from snapshot YAML header
+ let command = extract_command_from_snapshot(&raw);
+
let html_content = parse_snapshot_content_for_docs(&raw)?;
let normalized = trim_lines(&html_content);
- // Prepend command line with prompt styling if present
- Ok(match existing_command {
- Some(cmd) if cmd.starts_with("$ ") => {
- let cmd_text = cmd.strip_prefix("$ ").unwrap();
- format!(
- "<span class=\"prompt\">$</span> <span class=\"cmd\">{}</span>\n{}",
- cmd_text, normalized
- )
- }
- _ => normalized,
+ // Prepend command line with styling if present
+ // Prompt ($) is added via CSS ::before, so not included in HTML
+ Ok(match command {
+ Some(cmd) => format!("<span class=\"cmd\">{}</span>\n{}", cmd, normalized),
+ None => normalized,
})
},
) {
@@ -1321,21 +1400,6 @@ fn sync_command_pages(project_root: &Path) -> (Vec<String>, Vec<String>) {
(errors, updated_files)
}
-/// Strip HTML tags from a string (simple implementation for command extraction)
-fn strip_html_tags(s: &str) -> String {
- let mut result = String::new();
- let mut in_tag = false;
- for c in s.chars() {
- match c {
- '<' => in_tag = true,
- '>' => in_tag = false,
- _ if !in_tag => result.push(c),
- _ => {}
- }
- }
- result
-}
-
// =============================================================================
// Docs to Skill File Sync
// =============================================================================
diff --git a/tests/snapshots/integration__integration_tests__list__quickstart_list.snap b/tests/snapshots/integration__integration_tests__list__quickstart_list.snap
new file mode 100644
index 000000000..5992723a2
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__list__quickstart_list.snap
@@ -0,0 +1,41 @@
+---
+source: tests/integration_tests/list.rs
+info:
+ program: wt
+ args:
+ - list
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "98"
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+ Branch Status HEAD± main↕ Remote⇅ Commit Age Message
+@ feature-auth + – +53 0e631add 1d Initial commit
+^ main ^⇡ ⇡1 0e631add 1d Initial commit
+
+○ Showing 2 worktrees, 1 with changes, 1 column hidden
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__list__quickstart_merge.snap b/tests/snapshots/integration__integration_tests__list__quickstart_merge.snap
new file mode 100644
index 000000000..a986249ef
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__list__quickstart_merge.snap
@@ -0,0 +1,50 @@
+---
+source: tests/integration_tests/list.rs
+info:
+ program: wt
+ args:
+ - merge
+ - main
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_COMMIT__GENERATION__COMMAND: /private/var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmplWLZUt/mock-llm.sh
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_DIRECTIVE_FILE: "[DIRECTIVE_FILE]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Generating commit message and committing changes... (2 files, +53, no squashing needed)
+  Add authentication module
+✓ Committed changes @ [HASH]
+◎ Merging 1 commit to main @ [HASH] (no rebase needed)
+  * [HASH] Add authentication module
+  auth.rs | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
+  lib.rs | 2 ++
+  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_
diff --git a/tests/snapshots/integration__integration_tests__list__quickstart_switch.snap b/tests/snapshots/integration__integration_tests__list__quickstart_switch.snap
new file mode 100644
index 000000000..544e8ad95
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__list__quickstart_switch.snap
@@ -0,0 +1,40 @@
+---
+source: tests/integration_tests/list.rs
+info:
+ program: wt
+ args:
+ - switch
+ - "--create"
+ - feature-auth
+ 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]"
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_DIRECTIVE_FILE: "[DIRECTIVE_FILE]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+✓ Created branch feature-auth from main and worktree @ _REPO_.feature-auth