Skip to content

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

Refactor demo infrastructure: consolidate shared code and rename demos (#270)

Maximilian Roos96b8aa77577a
diff --git a/.config/lychee.toml b/.config/lychee.toml
index 612ba085f..5071f9bbf 100644
--- a/.config/lychee.toml
+++ b/.config/lychee.toml
@@ -66,6 +66,7 @@ exclude_path = [
".claude-plugin/skills/worktrunk/reference/README.md",
# Files with root-relative asset paths that lychee can't resolve
# (assets are fetched at deploy time from worktrunk-assets repo)
+ "docs/content/merge.md",
"docs/content/select.md",
"docs/content/why-worktrunk.md",
"docs/content/worktrunk.md",
diff --git a/.gitignore b/.gitignore
index 227b13c95..a6e9b478a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,5 @@
/target
-docs/demos/wt/out/
-docs/demos/wt-select/out/
+docs/demos/*/out/
docs/static/assets/
# Lychee link checker cache
diff --git a/README.md b/README.md
index 5c7557c4b..ac93fbd8e 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ Worktrunk is a CLI for git worktree management, designed for parallel AI agent w
Here's a quick demo:
-![Worktrunk Demo](https://cdn.jsdelivr.net/gh/max-sixty/worktrunk-assets@main/demos/wt-demo.gif)
+![Worktrunk Demo](https://cdn.jsdelivr.net/gh/max-sixty/worktrunk-assets@main/demos/wt-core.gif)
> ## ๐Ÿ“š Full documentation at [worktrunk.dev](https://worktrunk.dev) ๐Ÿ“š
diff --git a/dev/publish-assets b/dev/publish-assets
index 677b91c61..f54bd6f78 100755
--- a/dev/publish-assets
+++ b/dev/publish-assets
@@ -9,8 +9,10 @@ ASSETS_REPO="$REPO_ROOT/../worktrunk-assets"
# Demo sources: name|source_path
# Both light and dark variants for theme switching
DEMOS=(
- "wt-demo.gif|$REPO_ROOT/docs/demos/wt/out/wt-demo.gif"
- "wt-demo-dark.gif|$REPO_ROOT/docs/demos/wt/out/wt-demo-dark.gif"
+ "wt-core.gif|$REPO_ROOT/docs/demos/wt-core/out/wt-core.gif"
+ "wt-core-dark.gif|$REPO_ROOT/docs/demos/wt-core/out/wt-core-dark.gif"
+ "wt-merge.gif|$REPO_ROOT/docs/demos/wt-merge/out/wt-merge.gif"
+ "wt-merge-dark.gif|$REPO_ROOT/docs/demos/wt-merge/out/wt-merge-dark.gif"
"wt-select.gif|$REPO_ROOT/docs/demos/wt-select/out/wt-select.gif"
"wt-select-dark.gif|$REPO_ROOT/docs/demos/wt-select/out/wt-select-dark.gif"
)
@@ -50,7 +52,8 @@ done
if [[ ${#copied[@]} -eq 0 ]]; then
echo "No demo GIFs found. Build them first:"
- echo " ./docs/demos/wt/build"
+ echo " ./docs/demos/wt-core/build"
+ echo " ./docs/demos/wt-merge/build"
echo " ./docs/demos/wt-select/build"
exit 1
fi
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 3f28425ec..657e05529 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -267,9 +267,10 @@ Demo GIFs (~2MB each) are stored in a separate `worktrunk-assets` repo to avoid
**To regenerate demos** (required after CLI output changes):
1. Build the vhs-keystrokes binary if missing (one-time setup, see below)
-2. Run both demo build scripts:
+2. Run the demo build scripts:
```bash
- ./docs/demos/wt/build
+ ./docs/demos/wt-core/build
+ ./docs/demos/wt-merge/build
./docs/demos/wt-select/build
```
3. Publish: `./dev/publish-assets`
@@ -297,10 +298,11 @@ The `wt-select/build` script will skip GIF recording if the binary is missing an
### Light/dark theme variants
Each demo build generates both light and dark GIF variants:
-- `wt-demo.gif` / `wt-demo-dark.gif`
+- `wt-core.gif` / `wt-core-dark.gif`
+- `wt-merge.gif` / `wt-merge-dark.gif`
- `wt-select.gif` / `wt-select-dark.gif`
-Theme definitions are in `docs/demos/themes.py`, matching the CSS variables in `_variables.html`.
+Theme definitions are in `docs/demos/shared/themes.py`, matching the CSS variables in `_variables.html`.
In markdown, use `<picture>` with media queries:
```html
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 17799049e..dc68a1a8e 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -8,6 +8,13 @@ group = "Commands"
<!-- โš ๏ธ AUTO-GENERATED from `wt merge --help-page` โ€” edit cli.rs to update -->
+<figure class="demo">
+<picture>
+ <source srcset="/assets/wt-merge-dark.gif" media="(prefers-color-scheme: dark)">
+ <img src="/assets/wt-merge.gif" alt="wt merge demo" width="1600" height="900">
+</picture>
+</figure>
+
## Examples
Basic merge to main:
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index 2e7887a90..9705855f4 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -12,10 +12,10 @@ Here's a quick demo:
<figure class="demo">
<picture>
- <source srcset="/assets/wt-demo-dark.gif" media="(prefers-color-scheme: dark)">
- <img src="/assets/wt-demo.gif" alt="Worktrunk demo showing wt list, wt switch, and wt merge" width="1600" height="900">
+ <source srcset="/assets/wt-core-dark.gif" media="(prefers-color-scheme: dark)">
+ <img src="/assets/wt-core.gif" alt="Worktrunk demo showing wt list, wt switch, and hooks" width="1600" height="900">
</picture>
-<figcaption>Listing worktrees, creating a worktree, working, merging back</figcaption>
+<figcaption>Listing worktrees, switching, and hooks in action</figcaption>
</figure>
## Context: git worktrees
diff --git a/docs/demos/lib.py b/docs/demos/lib.py
deleted file mode 100644
index b9567ae4b..000000000
--- a/docs/demos/lib.py
+++ /dev/null
@@ -1,87 +0,0 @@
-"""Shared infrastructure for demo recording scripts."""
-
-import os
-import subprocess
-from dataclasses import dataclass
-from pathlib import Path
-
-from themes import THEMES, format_theme_for_vhs
-
-REAL_HOME = Path.home()
-
-
-@dataclass
-class DemoEnv:
- """Isolated demo environment with its own repo and home directory."""
-
- name: str
- out_dir: Path
- repo_name: str = "worktrunk"
-
- @property
- def root(self) -> Path:
- return self.out_dir / f".demo-{self.name}"
-
- @property
- def home(self) -> Path:
- return self.root
-
- @property
- def work_base(self) -> Path:
- return self.home / "w"
-
- @property
- def repo(self) -> Path:
- return self.work_base / self.repo_name
-
- @property
- def bare_remote(self) -> Path:
- return self.root / "remote.git"
-
-
-def run(cmd, cwd=None, env=None, check=True, capture=False):
- """Run a command."""
- result = subprocess.run(
- cmd, cwd=cwd, env=env, check=check,
- capture_output=capture, text=True
- )
- return result.stdout if capture else None
-
-
-def git(args, cwd=None, env=None):
- """Run git command."""
- run(["git"] + args, cwd=cwd, env=env)
-
-
-def render_tape(template_path: Path, output_path: Path, replacements: dict) -> bool:
- """Render a VHS tape template with variable substitutions.
-
- Args:
- template_path: Path to the .tape template file
- output_path: Path to write the rendered .tape file
- replacements: Dict of {{VAR}} -> value replacements
-
- Returns:
- True if successful, False if template doesn't exist
- """
- if not template_path.exists():
- print(f"Warning: {template_path} not found, skipping VHS recording")
- return False
-
- template = template_path.read_text()
- rendered = template
- for key, value in replacements.items():
- rendered = rendered.replace(f"{{{{{key}}}}}", str(value))
- output_path.write_text(rendered)
- return True
-
-
-def record_vhs(tape_path: Path, vhs_binary: str = "vhs"):
- """Record a demo GIF using VHS."""
- run([vhs_binary, str(tape_path)], check=True)
-
-
-def build_wt(repo_root: Path):
- """Build the wt binary."""
- print("Building wt binary...")
- run(["cargo", "build", "--quiet"], cwd=repo_root)
diff --git a/docs/demos/shared/__init__.py b/docs/demos/shared/__init__.py
new file mode 100644
index 000000000..82bf77e73
--- /dev/null
+++ b/docs/demos/shared/__init__.py
@@ -0,0 +1,34 @@
+"""Shared infrastructure for demo recording scripts."""
+
+from .lib import (
+ REAL_HOME,
+ FIXTURES_DIR,
+ DemoEnv,
+ run,
+ git,
+ render_tape,
+ record_vhs,
+ build_wt,
+ commit_dated,
+ prepare_base_repo,
+ setup_gh_mock,
+ prepare_demo_repo,
+)
+from .themes import THEMES, format_theme_for_vhs
+
+__all__ = [
+ "REAL_HOME",
+ "FIXTURES_DIR",
+ "DemoEnv",
+ "run",
+ "git",
+ "render_tape",
+ "record_vhs",
+ "build_wt",
+ "commit_dated",
+ "prepare_base_repo",
+ "setup_gh_mock",
+ "prepare_demo_repo",
+ "THEMES",
+ "format_theme_for_vhs",
+]
diff --git a/docs/demos/wt/fixtures/alpha-readme.md b/docs/demos/shared/fixtures/alpha-readme.md
similarity index 100%
rename from docs/demos/wt/fixtures/alpha-readme.md
rename to docs/demos/shared/fixtures/alpha-readme.md
diff --git a/docs/demos/wt/fixtures/gh-mock.sh b/docs/demos/shared/fixtures/gh-mock.sh
old mode 100644
new mode 100755
similarity index 54%
rename from docs/demos/wt/fixtures/gh-mock.sh
rename to docs/demos/shared/fixtures/gh-mock.sh
index 16bc6f026..5b7ecdfad
--- a/docs/demos/wt/fixtures/gh-mock.sh
+++ b/docs/demos/shared/fixtures/gh-mock.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-# Mock gh CLI for demo
+# Mock gh CLI for demos - returns varied CI status per branch
if [[ "$1" == "auth" && "$2" == "status" ]]; then
exit 0
@@ -15,6 +15,9 @@ if [[ "$1" == "pr" && "$2" == "list" ]]; then
done
case "$branch" in
+ main)
+ echo '[{"state":"MERGED","headRefOid":"main123","mergeStateStatus":"CLEAN","statusCheckRollup":[{"status":"COMPLETED","conclusion":"SUCCESS"}],"url":"https://github.com/acme/demo/pull/100"}]'
+ ;;
alpha)
echo '[{"state":"OPEN","headRefOid":"abc123","mergeStateStatus":"CLEAN","statusCheckRollup":[{"status":"COMPLETED","conclusion":"SUCCESS"}],"url":"https://github.com/acme/demo/pull/1"}]'
;;
@@ -22,7 +25,11 @@ if [[ "$1" == "pr" && "$2" == "list" ]]; then
echo '[{"state":"OPEN","headRefOid":"def456","mergeStateStatus":"CLEAN","statusCheckRollup":[{"status":"IN_PROGRESS","conclusion":null}],"url":"https://github.com/acme/demo/pull/2"}]'
;;
hooks)
- echo '[{"state":"OPEN","headRefOid":"ghi789","mergeStateStatus":"CLEAN","statusCheckRollup":[{"status":"COMPLETED","conclusion":"FAILURE"}],"url":"https://github.com/acme/demo/pull/3"}]'
+ # hooks has no remote, so no PR
+ echo '[]'
+ ;;
+ billing|api)
+ echo '[{"state":"OPEN","headRefOid":"jkl012","mergeStateStatus":"CLEAN","statusCheckRollup":[{"status":"COMPLETED","conclusion":"SUCCESS"}],"url":"https://github.com/acme/demo/pull/4"}]'
;;
*)
echo '[]'
@@ -31,23 +38,11 @@ if [[ "$1" == "pr" && "$2" == "list" ]]; then
exit 0
fi
-if [[ "$1" == "run" && "$2" == "list" ]]; then
- branch=""
- for arg in "$@"; do
- if [[ "$prev" == "--branch" ]]; then
- branch="$arg"
- fi
- prev="$arg"
- done
-
- case "$branch" in
- main)
- echo '[{"status":"completed","conclusion":"success","headSha":"abc123"}]'
- ;;
- *)
- echo '[]'
- ;;
- esac
+# gh api for check-runs (branches without PRs, like main)
+# wt calls: gh api repos/.../commits/.../check-runs --jq '.check_runs | map({status, conclusion})'
+# We return the post-jq result directly
+if [[ "$1" == "api" && "$2" == *"check-runs"* ]]; then
+ echo '[{"status":"completed","conclusion":"success"}]'
exit 0
fi
diff --git a/docs/demos/wt/fixtures/lib-hooks.rs b/docs/demos/shared/fixtures/lib-hooks.rs
similarity index 100%
rename from docs/demos/wt/fixtures/lib-hooks.rs
rename to docs/demos/shared/fixtures/lib-hooks.rs
diff --git a/docs/demos/wt/fixtures/lib.rs b/docs/demos/shared/fixtures/lib.rs
similarity index 100%
rename from docs/demos/wt/fixtures/lib.rs
rename to docs/demos/shared/fixtures/lib.rs
diff --git a/docs/demos/wt-select/fixtures/starship.toml b/docs/demos/shared/fixtures/starship.toml
similarity index 100%
rename from docs/demos/wt-select/fixtures/starship.toml
rename to docs/demos/shared/fixtures/starship.toml
diff --git a/docs/demos/shared/lib.py b/docs/demos/shared/lib.py
new file mode 100644
index 000000000..72afcef67
--- /dev/null
+++ b/docs/demos/shared/lib.py
@@ -0,0 +1,346 @@
+"""Shared infrastructure for demo recording scripts."""
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+
+REAL_HOME = Path.home()
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+
+
+@dataclass
+class DemoEnv:
+ """Isolated demo environment with its own repo and home directory."""
+
+ name: str
+ out_dir: Path
+ repo_name: str = "worktrunk"
+
+ @property
+ def root(self) -> Path:
+ return self.out_dir / f".demo-{self.name}"
+
+ @property
+ def home(self) -> Path:
+ return self.root
+
+ @property
+ def work_base(self) -> Path:
+ return self.home / "w"
+
+ @property
+ def repo(self) -> Path:
+ return self.work_base / self.repo_name
+
+ @property
+ def bare_remote(self) -> Path:
+ return self.root / "remote.git"
+
+
+def run(cmd, cwd=None, env=None, check=True, capture=False):
+ """Run a command."""
+ result = subprocess.run(
+ cmd, cwd=cwd, env=env, check=check,
+ capture_output=capture, text=True
+ )
+ return result.stdout if capture else None
+
+
+def git(args, cwd=None, env=None):
+ """Run git command."""
+ run(["git"] + args, cwd=cwd, env=env)
+
+
+def render_tape(template_path: Path, output_path: Path, replacements: dict) -> bool:
+ """Render a VHS tape template with variable substitutions.
+
+ Args:
+ template_path: Path to the .tape template file
+ output_path: Path to write the rendered .tape file
+ replacements: Dict of {{VAR}} -> value replacements
+
+ Returns:
+ True if successful, False if template doesn't exist
+ """
+ if not template_path.exists():
+ print(f"Warning: {template_path} not found, skipping VHS recording")
+ return False
+
+ template = template_path.read_text()
+ rendered = template
+ for key, value in replacements.items():
+ rendered = rendered.replace(f"{{{{{key}}}}}", str(value))
+ output_path.write_text(rendered)
+ return True
+
+
+def record_vhs(tape_path: Path, vhs_binary: str = "vhs"):
+ """Record a demo GIF using VHS."""
+ run([vhs_binary, str(tape_path)], check=True)
+
+
+def build_wt(repo_root: Path):
+ """Build the wt binary."""
+ print("Building wt binary...")
+ run(["cargo", "build", "--quiet"], cwd=repo_root)
+
+
+def commit_dated(repo: Path, message: str, offset: str, env_extra: dict = None):
+ """Commit with a date offset like '7d' or '2H'."""
+ now = datetime.now()
+ if offset.endswith("d"):
+ delta = timedelta(days=int(offset[:-1]))
+ elif offset.endswith("H"):
+ delta = timedelta(hours=int(offset[:-1]))
+ else:
+ raise ValueError(f"Unknown offset format: {offset}")
+
+ date_str = (now - delta).strftime("%Y-%m-%dT%H:%M:%S")
+ env = os.environ.copy()
+ env["GIT_AUTHOR_DATE"] = date_str
+ env["GIT_COMMITTER_DATE"] = date_str
+ env["SKIP_DEMO_HOOK"] = "1"
+ if env_extra:
+ env.update(env_extra)
+ git(["-C", str(repo), "commit", "-qm", message], env=env)
+
+
+def prepare_base_repo(env: DemoEnv, repo_root: Path):
+ """Set up the base demo repository with Rust project.
+
+ Creates:
+ - Git repo with initial commit
+ - Rust project (Cargo.toml, lib.rs, Cargo.lock)
+ - Mock gh CLI for CI status
+ - bat wrapper for syntax highlighting
+ - User config directory
+
+ Demos should call this first, then add their own:
+ - Project hooks config (.config/wt.toml)
+ - Branches and worktrees
+ - Additional mock CLIs
+ - Approved commands in user config
+ """
+ # Clean previous
+ shutil.rmtree(env.root, ignore_errors=True)
+
+ env.root.mkdir(parents=True)
+ env.work_base.mkdir(parents=True)
+ env.repo.mkdir(parents=True)
+
+ # Init bare remote
+ run(["git", "init", "--bare", "-q", str(env.bare_remote)])
+
+ # Init main repo
+ git(["-C", str(env.repo), "init", "-q"])
+ git(["-C", str(env.repo), "config", "user.name", "Worktrunk Demo"])
+ git(["-C", str(env.repo), "config", "user.email", "[email protected]"])
+ git(["-C", str(env.repo), "config", "commit.gpgsign", "false"])
+
+ # Initial commit
+ (env.repo / "README.md").write_text("# Acme App\n\nA demo application.\n")
+ git(["-C", str(env.repo), "add", "README.md"])
+ commit_dated(env.repo, "Initial commit", "7d")
+ git(["-C", str(env.repo), "branch", "-m", "main"])
+ # Use local bare repo as remote (GitHub URLs cause VHS to hang waiting for SSH)
+ git(["-C", str(env.repo), "remote", "add", "origin", str(env.bare_remote)])
+ git(["-C", str(env.repo), "push", "-u", "origin", "main", "-q"])
+
+ # Rust project
+ (env.repo / "Cargo.toml").write_text(
+ "[package]\nname = \"acme\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n[workspace]\n"
+ )
+ (env.repo / "src").mkdir()
+ shutil.copy(FIXTURES_DIR / "lib.rs", env.repo / "src" / "lib.rs")
+ (env.repo / ".gitignore").write_text("/target\n")
+ git(["-C", str(env.repo), "add", ".gitignore", "Cargo.toml", "src/"])
+ commit_dated(env.repo, "Add Rust project with tests", "6d")
+
+ # Build to create Cargo.lock
+ run(["cargo", "build", "--release", "-q"], cwd=env.repo, check=False)
+ git(["-C", str(env.repo), "add", "Cargo.lock"])
+ commit_dated(env.repo, "Add Cargo.lock", "6d")
+ git(["-C", str(env.repo), "push", "-q"])
+
+ # Mock CLI tools
+ bin_dir = env.home / "bin"
+ bin_dir.mkdir(parents=True, exist_ok=True)
+
+ # bat wrapper for syntax highlighting (alias cat to bat for toml files)
+ bat_wrapper = bin_dir / "cat"
+ bat_wrapper.write_text("""#!/bin/bash
+# Use bat for syntax highlighting if file is toml
+if [[ "$1" == *.toml ]]; then
+ exec bat --style=plain --paging=never "$@"
+else
+ exec /bin/cat "$@"
+fi
+""")
+ bat_wrapper.chmod(0o755)
+
+ # Build wt binary
+ build_wt(repo_root)
+
+ # User config directory (demos add their own config.toml)
+ config_dir = env.home / ".config" / "worktrunk"
+ config_dir.mkdir(parents=True)
+
+ # Project config directory
+ (env.repo / ".config").mkdir(exist_ok=True)
+
+
+def setup_gh_mock(env: DemoEnv, fixtures_dir: Path):
+ """Set up gh CLI mock from demo's fixtures directory."""
+ bin_dir = env.home / "bin"
+ bin_dir.mkdir(parents=True, exist_ok=True)
+ gh_mock = bin_dir / "gh"
+ shutil.copy(fixtures_dir / "gh-mock.sh", gh_mock)
+ gh_mock.chmod(0o755)
+
+
+def prepare_demo_repo(env: DemoEnv, repo_root: Path, hooks_config: str = None):
+ """Set up a full demo repository with varied branches.
+
+ Creates a rich repo for great `wt list` output:
+ - Git repo with Rust project
+ - Mock gh CLI for CI status (generic version)
+ - bat wrapper for syntax highlighting
+ - Extra branches without worktrees (docs/readme, spike/search)
+ - alpha: large diff, unpushed commits, behind main
+ - beta: staged changes, behind main
+ - hooks: no remote, staged+unstaged changes
+
+ Args:
+ env: Demo environment
+ repo_root: Path to worktrunk repo for building wt
+ hooks_config: Optional project hooks (.config/wt.toml) content.
+ If None, uses default pre-merge hook.
+
+ After calling this, main is at the latest commit and worktrees exist for
+ alpha, beta, hooks. Demos can then add their own branches/config.
+ """
+ # Base setup: git repo, Rust project, bat wrapper, wt binary
+ prepare_base_repo(env, repo_root)
+
+ # Project hooks
+ if hooks_config is None:
+ hooks_config = '[pre-merge]\ntest = "cargo nextest run"\n'
+ (env.repo / ".config" / "wt.toml").write_text(hooks_config)
+ git(["-C", str(env.repo), "add", ".config/wt.toml"])
+ commit_dated(env.repo, "Add project hooks", "5d")
+ git(["-C", str(env.repo), "push", "-q"])
+
+ # Mock gh CLI with varied CI status per branch
+ bin_dir = env.home / "bin"
+ gh_mock = bin_dir / "gh"
+ shutil.copy(FIXTURES_DIR / "gh-mock.sh", gh_mock)
+ gh_mock.chmod(0o755)
+
+ # Extra branches without worktrees (for --branches view)
+ git(["-C", str(env.repo), "branch", "docs/readme"])
+ git(["-C", str(env.repo), "branch", "spike/search"])
+
+ # Create beta first (from current main, so it will be behind after main commit)
+ _create_branch_beta(env)
+
+ # Commit to main so beta is behind
+ readme = env.repo / "README.md"
+ readme.write_text(readme.read_text() + "\n## Development\n\nSee CONTRIBUTING.md for guidelines.\n")
+ (env.repo / "notes.md").write_text("# Notes\n")
+ git(["-C", str(env.repo), "add", "README.md", "notes.md"])
+ commit_dated(env.repo, "docs: add development section", "1d")
+ git(["-C", str(env.repo), "push", "-q"])
+
+ # Create alpha and hooks after the main commit (so they're only ahead, not diverged)
+ _create_branch_alpha(env)
+ _create_branch_hooks(env)
+
+
+def _create_branch_alpha(env: DemoEnv):
+ """Create alpha branch with large diff and unpushed commits."""
+ branch = "alpha"
+ path = env.work_base / f"acme.{branch}"
+
+ git(["-C", str(env.repo), "checkout", "-q", "-b", branch, "main"])
+
+ # Initial README changes
+ (env.repo / "README.md").write_text('''# Acme App
+
+A demo application for showcasing worktrunk features.
+
+## Features
+
+- Fast worktree switching
+- Integrated merge workflow
+- Pre-merge test hooks
+- LLM commit messages
+
+## Getting Started
+
+Run `wt list` to see all worktrees.
+''')
+ git(["-C", str(env.repo), "add", "README.md"])
+ commit_dated(env.repo, "docs: expand README", "3d")
+
+ # More commits
+ readme = env.repo / "README.md"
+ readme.write_text(readme.read_text() + "\n## Contributing\n\nPRs welcome!\n")
+ git(["-C", str(env.repo), "add", "README.md"])
+ commit_dated(env.repo, "docs: add contributing section", "3d")
+
+ readme.write_text(readme.read_text() + "\n## License\n\nMIT\n")
+ git(["-C", str(env.repo), "add", "README.md"])
+ commit_dated(env.repo, "docs: add license", "3d")
+
+ git(["-C", str(env.repo), "push", "-u", "origin", branch, "-q"])
+ git(["-C", str(env.repo), "checkout", "-q", "main"])
+ git(["-C", str(env.repo), "worktree", "add", "-q", str(path), branch])
+
+ # Unpushed commit
+ readme = path / "README.md"
+ readme.write_text(readme.read_text() + "## FAQ\n\n")
+ git(["-C", str(path), "add", "README.md"])
+ commit_dated(path, "docs: add FAQ section", "3d")
+
+ # Working tree changes - large diff using shared fixture
+ shutil.copy(FIXTURES_DIR / "alpha-readme.md", path / "README.md")
+ (path / "scratch.rs").write_text("// scratch\n")
+
+
+def _create_branch_beta(env: DemoEnv):
+ """Create beta branch with staged changes and remote tracking."""
+ branch = "beta"
+ path = env.work_base / f"acme.{branch}"
+
+ git(["-C", str(env.repo), "checkout", "-q", "-b", branch, "main"])
+ git(["-C", str(env.repo), "push", "-u", "origin", branch, "-q"])
+ git(["-C", str(env.repo), "checkout", "-q", "main"])
+ git(["-C", str(env.repo), "worktree", "add", "-q", str(path), branch])
+
+ # Staged new file
+ (path / "notes.txt").write_text("# TODO\n- Add caching\n")
+ git(["-C", str(path), "add", "notes.txt"])
+
+
+def _create_branch_hooks(env: DemoEnv):
+ """Create hooks branch with refactored lib.rs, no remote."""
+ branch = "hooks"
+ path = env.work_base / f"acme.{branch}"
+
+ git(["-C", str(env.repo), "checkout", "-q", "-b", branch, "main"])
+ shutil.copy(FIXTURES_DIR / "lib-hooks.rs", env.repo / "src" / "lib.rs")
+ git(["-C", str(env.repo), "add", "src/lib.rs"])
+ commit_dated(env.repo, "feat: add math operations, consolidate tests", "2H")
+
+ # No push - no upstream
+ git(["-C", str(env.repo), "checkout", "-q", "main"])
+ git(["-C", str(env.repo), "worktree", "add", "-q", str(path), branch])
+
+ # Staged then modified
+ lib_rs = path / "src" / "lib.rs"
+ lib_rs.write_text(lib_rs.read_text() + "// Division coming soon\n")
+ git(["-C", str(path), "add", "src/lib.rs"])
+ lib_rs.write_text(lib_rs.read_text() + "// TODO: add division\n")
diff --git a/docs/demos/themes.py b/docs/demos/shared/themes.py
similarity index 100%
rename from docs/demos/themes.py
rename to docs/demos/shared/themes.py
diff --git a/docs/demos/wt-core/build b/docs/demos/wt-core/build
new file mode 100755
index 000000000..f4989b6ff
--- /dev/null
+++ b/docs/demos/wt-core/build
@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""Build script for wt-core demo GIF.
+
+This demo shows the core workflow with hooks:
+1. wt list - see current worktrees with variety
+2. wt switch - switch between worktrees
+3. Show the post-start/pre-remove config
+4. wt switch --create - create worktree with post-start running
+5. wt list --full - show CI status
+6. wt remove - remove worktree with pre-remove hook
+"""
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# Add docs/demos/ to path for shared library
+SCRIPT_DIR = Path(__file__).parent
+DEMOS_DIR = SCRIPT_DIR.parent
+sys.path.insert(0, str(DEMOS_DIR))
+
+from shared import (
+ DemoEnv, run, git, render_tape, record_vhs, REAL_HOME, FIXTURES_DIR,
+ prepare_demo_repo, commit_dated, THEMES, format_theme_for_vhs,
+)
+
+REPO_ROOT = DEMOS_DIR.parent.parent
+OUT_DIR = SCRIPT_DIR / "out"
+TAPE_TEMPLATE = SCRIPT_DIR / "demo.tape"
+TAPE_RENDERED = OUT_DIR / ".rendered.tape"
+STARSHIP_CONFIG = OUT_DIR / "starship.toml"
+
+# Output GIF paths for light and dark variants
+OUTPUT_GIFS = {
+ "light": OUT_DIR / "wt-core.gif",
+ "dark": OUT_DIR / "wt-core-dark.gif",
+}
+
+
+def prepare_repo(env: DemoEnv):
+ """Set up the demo repository with branches and worktrees."""
+ # Use shared rich repo setup with custom hooks config
+ hooks_config = '''[post-start]
+dev = "npm run dev"
+
+[pre-remove]
+cleanup = "flyctl scale count 0"
+'''
+ prepare_demo_repo(env, REPO_ROOT, hooks_config=hooks_config)
+
+ # Demo-specific: mock CLIs for hooks
+ bin_dir = env.home / "bin"
+
+ npm_mock = bin_dir / "npm"
+ npm_mock.write_text("""#!/bin/bash
+if [[ "$1" == "run" && "$2" == "dev" ]]; then
+ echo ""
+ echo " VITE v5.4.2 ready in 342 ms"
+ echo ""
+ echo " โžœ Local: http://localhost:3000/"
+ echo " โžœ Network: http://192.168.1.42:3000/"
+fi
+""")
+ npm_mock.chmod(0o755)
+
+ flyctl_mock = bin_dir / "flyctl"
+ flyctl_mock.write_text("""#!/bin/bash
+if [[ "$1" == "scale" && "$2" == "count" && "$3" == "0" ]]; then
+ echo "Scaling app to 0 machines"
+fi
+""")
+ flyctl_mock.chmod(0o755)
+
+ # Demo-specific: user config with approved commands
+ # Project ID for local path is the path without .git suffix
+ config_dir = env.home / ".config" / "worktrunk"
+ project_id = str(env.bare_remote).removesuffix(".git")
+ (config_dir / "config.toml").write_text(f'''[projects."{project_id}"]
+approved-commands = ["npm run dev", "flyctl scale count 0"]
+''')
+
+ # Add billing branch (at same commit as main = merged)
+ create_branch_billing(env)
+
+
+def create_branch_billing(env: DemoEnv):
+ """Create billing branch that's already merged (at same commit as main)."""
+ branch = "billing"
+ path = env.work_base / f"acme.{branch}"
+
+ # Create worktree at main's commit (so it shows as merged/safe to delete)
+ git(["-C", str(env.repo), "worktree", "add", "-q", "-b", branch, str(path), "main"])
+ git(["-C", str(path), "push", "-u", "origin", branch, "-q"])
+
+
+def record_text(demo_env: DemoEnv):
+ """Record text output by running demo commands."""
+ # Commands to run (matching demo.tape)
+ commands = [
+ "wt list",
+ "wt switch alpha",
+ "cat .config/wt.toml",
+ "wt switch --create api",
+ "wt list --full",
+ "wt switch billing",
+ "wt remove",
+ ]
+
+ # Set up environment
+ env = os.environ.copy()
+ env.update({
+ "LANG": "en_US.UTF-8",
+ "LC_ALL": "en_US.UTF-8",
+ "COLUMNS": "140",
+ "RUSTUP_HOME": str(REAL_HOME / ".rustup"),
+ "CARGO_HOME": str(REAL_HOME / ".cargo"),
+ "HOME": str(demo_env.home),
+ "PATH": f"{REPO_ROOT}/target/debug:{demo_env.home}/bin:{os.environ['PATH']}",
+ "STARSHIP_CONFIG": str(STARSHIP_CONFIG),
+ "STARSHIP_CACHE": str(demo_env.root / "starship-cache"),
+ "NO_COLOR": "1",
+ "CLICOLOR": "0",
+ })
+
+ (demo_env.root / "starship-cache").mkdir(exist_ok=True)
+
+ # Run commands and capture output using fish with shell init
+ script = "wt config shell init fish | source\n"
+ for cmd in commands:
+ script += f"echo '$ {cmd}'\n{cmd}\necho ''\n"
+
+ result = subprocess.run(
+ ["fish", "-c", script],
+ cwd=demo_env.repo, env=env,
+ capture_output=True, text=True
+ )
+ output = result.stdout + result.stderr
+
+ # Clean output
+ clean = re.sub(r"\x1B\[[0-9;?]*[A-Za-z]", "", output) # Strip ANSI
+ clean = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]", "", clean) # Strip control chars
+
+ (OUT_DIR / "run.txt").write_text(clean)
+
+
+def main():
+ # Check dependencies
+ for cmd in ["wt", "vhs", "starship", "bat"]:
+ if not shutil.which(cmd):
+ raise SystemExit(f"Missing dependency: {cmd}")
+
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+ # Copy starship config from fixtures
+ shutil.copy(FIXTURES_DIR / "starship.toml", STARSHIP_CONFIG)
+
+ # Create separate environments for text and VHS recording
+ # so they don't interfere with each other
+ text_env = DemoEnv(name="text", out_dir=OUT_DIR, repo_name="acme")
+ vhs_env = DemoEnv(name="vhs", out_dir=OUT_DIR, repo_name="acme")
+
+ prepare_repo(text_env)
+ record_text(text_env)
+
+ prepare_repo(vhs_env)
+
+ # Record both light and dark variants
+ docs_assets = REPO_ROOT / "docs" / "static" / "assets"
+ docs_assets.mkdir(parents=True, exist_ok=True)
+
+ for theme_name, output_gif in OUTPUT_GIFS.items():
+ theme = THEMES[theme_name]
+ replacements = {
+ "DEMO_REPO": vhs_env.repo,
+ "DEMO_HOME": vhs_env.home,
+ "REAL_HOME": REAL_HOME,
+ "STARSHIP_CONFIG": STARSHIP_CONFIG,
+ "OUTPUT_GIF": output_gif,
+ "TARGET_DEBUG": REPO_ROOT / "target" / "debug",
+ "THEME": format_theme_for_vhs(theme),
+ }
+ render_tape(TAPE_TEMPLATE, TAPE_RENDERED, replacements)
+ print(f"\nRecording {theme_name} GIF...")
+ record_vhs(TAPE_RENDERED)
+ TAPE_RENDERED.unlink(missing_ok=True)
+ print(f"GIF saved to {output_gif}")
+
+ # Copy to docs for local preview
+ asset_name = output_gif.name
+ shutil.copy(output_gif, docs_assets / asset_name)
+ print(f"Copied to {docs_assets / asset_name}")
+
+ print(f"\nText log saved to {OUT_DIR / 'run.txt'}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docs/demos/wt-core/demo.tape b/docs/demos/wt-core/demo.tape
new file mode 100644
index 000000000..ce7488217
--- /dev/null
+++ b/docs/demos/wt-core/demo.tape
@@ -0,0 +1,82 @@
+Output "{{OUTPUT_GIF}}"
+
+Require wt
+Require git
+
+Set Shell "fish"
+Set FontSize 24
+Set FontFamily "Geist Mono, Berkeley Mono, Fira Code, JetBrains Mono, Menlo, Apple Color Emoji"
+Set Width 1600
+Set Height 900
+Set Theme {{THEME}}
+Set Padding 18
+Set LineHeight 1.12
+Set TypingSpeed 28ms
+Set CursorBlink false
+Set Framerate 30
+
+Env DEMO_REPO "{{DEMO_REPO}}"
+Env RUSTUP_HOME "{{REAL_HOME}}/.rustup"
+Env CARGO_HOME "{{REAL_HOME}}/.cargo"
+Env HOME "{{DEMO_HOME}}"
+Env XDG_CONFIG_HOME "{{DEMO_HOME}}/.config"
+Env STARSHIP_CONFIG "{{STARSHIP_CONFIG}}"
+Env GIT_TERMINAL_PROMPT "0"
+
+Hide
+Type "set -g fish_autosuggestion_enabled 0"
+Enter
+Type "set -gx LANG en_US.UTF-8; set -gx LC_ALL en_US.UTF-8"
+Enter
+Type "set -gx PATH {{TARGET_DEBUG}} $HOME/bin $PATH"
+Enter
+Type "starship init fish | source"
+Enter
+Type "wt config shell init fish | source"
+Enter
+Type "cd $DEMO_REPO"
+Enter
+Type "clear"
+Enter
+Sleep 500ms
+Show
+Sleep 500ms
+
+# 1. Show current worktrees
+Type "wt list"
+Enter
+Sleep 2s
+
+# 2. Switch to alpha worktree
+Type "wt switch alpha"
+Enter
+Sleep 1s
+
+# 3. Show the hooks config (bat syntax highlighting via cat wrapper)
+Type "cat .config/wt.toml"
+Enter
+Sleep 2s
+
+# 4. Create new worktree with post-start
+Type "wt switch --create api"
+Enter
+Sleep 2.5s
+
+# 5. Show full list with CI status
+Type "wt list --full"
+Enter
+Sleep 2.5s
+
+# 6. Switch to billing (already merged)
+Type "wt switch billing"
+Enter
+Sleep 1.5s
+
+# 7. Remove the merged worktree (pre-remove hook runs)
+Type "wt remove"
+Enter
+Sleep 5s
+
+Type "exit"
+Enter
+Sleep 500ms
diff --git a/docs/demos/wt-merge/build b/docs/demos/wt-merge/build
new file mode 100755
index 000000000..195f17982
--- /dev/null
+++ b/docs/demos/wt-merge/build
@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Build script for wt-merge demo GIF."""
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+# Add docs/demos/ to path for shared library
+SCRIPT_DIR = Path(__file__).parent
+DEMOS_DIR = SCRIPT_DIR.parent
+sys.path.insert(0, str(DEMOS_DIR))
+
+from shared import (
+ DemoEnv, run, git, render_tape, record_vhs, REAL_HOME, FIXTURES_DIR,
+ prepare_demo_repo, THEMES, format_theme_for_vhs,
+)
+
+REPO_ROOT = DEMOS_DIR.parent.parent
+OUT_DIR = SCRIPT_DIR / "out"
+TAPE_TEMPLATE = SCRIPT_DIR / "demo.tape"
+TAPE_RENDERED = OUT_DIR / ".rendered.tape"
+STARSHIP_CONFIG = OUT_DIR / "starship.toml"
+
+# Output GIF paths for light and dark variants
+OUTPUT_GIFS = {
+ "light": OUT_DIR / "wt-merge.gif",
+ "dark": OUT_DIR / "wt-merge-dark.gif",
+}
+
+
+def prepare_repo(env: DemoEnv):
+ """Set up the demo repository using shared setup plus wt-specific config."""
+ # Use shared rich repo setup
+ prepare_demo_repo(env, REPO_ROOT)
+
+ # wt demo-specific: user config with llm commit generation
+ config_dir = env.home / ".config" / "worktrunk"
+ project_id = str(env.bare_remote).removesuffix(".git")
+ (config_dir / "config.toml").write_text(f'''[commit-generation]
+command = "llm"
+args = ["-m", "claude-haiku-4.5"]
+
+[projects."{project_id}"]
+approved-commands = ["cargo nextest run"]
+''')
+
+
+def record_text(demo_env: DemoEnv):
+ """Record text output by running demo commands."""
+ # Extract commands from tape
+ commands = []
+ for line in TAPE_TEMPLATE.read_text().splitlines():
+ if line.startswith("Type "):
+ cmd = line[5:].strip().strip('"').strip("'")
+ # Skip setup commands (fish uses 'set -gx' instead of 'export')
+ if not any(cmd.startswith(p) for p in ["set -gx", "export ", "eval ", "cd ", "clear", "exit", "starship init", "wt config shell init"]):
+ commands.append(cmd)
+
+ # Set up environment
+ env = os.environ.copy()
+ env.update({
+ "LANG": "en_US.UTF-8",
+ "LC_ALL": "en_US.UTF-8",
+ "COLUMNS": "160",
+ "RUSTUP_HOME": str(REAL_HOME / ".rustup"),
+ "CARGO_HOME": str(REAL_HOME / ".cargo"),
+ "HOME": str(demo_env.home),
+ "PATH": f"{REPO_ROOT}/target/debug:{demo_env.home}/bin:{os.environ['PATH']}",
+ "STARSHIP_CONFIG": str(STARSHIP_CONFIG),
+ "STARSHIP_CACHE": str(demo_env.root / "starship-cache"),
+ "NO_COLOR": "1",
+ "CLICOLOR": "0",
+ "NEXTEST_STATUS_LEVEL": "none",
+ "NEXTEST_FINAL_STATUS_LEVEL": "flaky",
+ "NEXTEST_NO_FAIL_FAST": "1",
+ })
+
+ (demo_env.root / "starship-cache").mkdir(exist_ok=True)
+
+ # Run commands and capture output using fish with shell init
+ script = '''wt config shell init fish | source
+'''
+ for cmd in commands:
+ script += f'{cmd}\n'
+ if cmd.startswith("wt merge"):
+ script += 'sleep 2\n'
+
+ result = subprocess.run(
+ ["fish", "-c", script],
+ cwd=demo_env.repo, env=env,
+ capture_output=True, text=True
+ )
+ output = [result.stdout + result.stderr]
+
+ # Clean output
+ raw = "".join(output)
+ clean = re.sub(r"\x1B\[[0-9;?]*[A-Za-z]", "", raw) # Strip ANSI
+ clean = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]", "", clean) # Strip control chars
+ clean = clean.replace("^D", "")
+
+ (OUT_DIR / "run.txt").write_text(clean)
+
+
+def main():
+ # Check dependencies
+ for cmd in ["wt", "vhs", "starship"]:
+ if not shutil.which(cmd):
+ raise SystemExit(f"Missing dependency: {cmd}")
+
+ OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+ # Copy starship config from fixtures
+ shutil.copy(FIXTURES_DIR / "starship.toml", STARSHIP_CONFIG)
+
+ # Create separate environments for text and VHS recording
+ # so they don't interfere with each other (different LLM-generated commits)
+ text_env = DemoEnv(name="text", out_dir=OUT_DIR, repo_name="acme")
+ vhs_env = DemoEnv(name="vhs", out_dir=OUT_DIR, repo_name="acme")
+
+ prepare_repo(text_env)
+ record_text(text_env)
+
+ prepare_repo(vhs_env)
+
+ # Record both light and dark variants
+ docs_assets = REPO_ROOT / "docs" / "static" / "assets"
+ docs_assets.mkdir(parents=True, exist_ok=True)
+
+ for theme_name, output_gif in OUTPUT_GIFS.items():
+ theme = THEMES[theme_name]
+ replacements = {
+ "DEMO_REPO": vhs_env.repo,
+ "DEMO_HOME": vhs_env.home,
+ "REAL_HOME": REAL_HOME,
+ "STARSHIP_CONFIG": STARSHIP_CONFIG,
+ "OUTPUT_GIF": output_gif,
+ "TARGET_DEBUG": REPO_ROOT / "target" / "debug",
+ "THEME": format_theme_for_vhs(theme),
+ }
+ render_tape(TAPE_TEMPLATE, TAPE_RENDERED, replacements)
+ print(f"\nRecording {theme_name} GIF...")
+ record_vhs(TAPE_RENDERED)
+ TAPE_RENDERED.unlink(missing_ok=True)
+ print(f"GIF saved to {output_gif}")
+
+ # Copy to docs for local preview
+ asset_name = output_gif.name
+ shutil.copy(output_gif, docs_assets / asset_name)
+ print(f"Copied to {docs_assets / asset_name}")
+
+ print(f"\nText log saved to {OUT_DIR / 'run.txt'}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docs/demos/wt/demo.tape b/docs/demos/wt-merge/demo.tape
similarity index 100%
rename from docs/demos/wt/demo.tape
rename to docs/demos/wt-merge/demo.tape
diff --git a/docs/demos/wt-select/.gitignore b/docs/demos/wt-select/.gitignore
deleted file mode 100644
index bab312f80..000000000
--- a/docs/demos/wt-select/.gitignore
+++ /dev/null
@@ -1,5 +0,0 @@
-# Build output
-out/
-
-# Custom VHS fork (built locally)
-vhs-keystrokes/
diff --git a/docs/demos/wt-select/CLAUDE.md b/docs/demos/wt-select/CLAUDE.md
index b65f8a985..c9a619127 100644
--- a/docs/demos/wt-select/CLAUDE.md
+++ b/docs/demos/wt-select/CLAUDE.md
@@ -116,9 +116,10 @@ ffmpeg -i demo.gif -vsync 0 /tmp/gif-frames/frame_%04d.png
- `build` - Main build script
- `demo.tape` - VHS tape file with recording script
-- `fixtures/` - Starship config and other fixtures
- `out/` - Output directory (gitignored)
+Starship config comes from shared `docs/demos/fixtures/`.
+
## Updating Commits
To update the cherry-picked commits, edit `CHERRY_PICKS` in `build`:
diff --git a/docs/demos/wt-select/build b/docs/demos/wt-select/build
index 3cbd3f149..9306514af 100755
--- a/docs/demos/wt-select/build
+++ b/docs/demos/wt-select/build
@@ -62,11 +62,12 @@ SCRIPT_DIR = Path(__file__).parent
DEMOS_DIR = SCRIPT_DIR.parent
sys.path.insert(0, str(DEMOS_DIR))
-from lib import DemoEnv, run, git, render_tape, record_vhs, build_wt, REAL_HOME
-from themes import THEMES, format_theme_for_vhs
+from shared import (
+ DemoEnv, run, git, render_tape, record_vhs, build_wt, REAL_HOME, FIXTURES_DIR,
+ THEMES, format_theme_for_vhs,
+)
REPO_ROOT = DEMOS_DIR.parent.parent
-FIXTURES_DIR = SCRIPT_DIR / "fixtures"
OUT_DIR = SCRIPT_DIR / "out"
TAPE_TEMPLATE = SCRIPT_DIR / "demo.tape"
TAPE_RENDERED = OUT_DIR / ".rendered.tape"
diff --git a/docs/demos/wt/build b/docs/demos/wt/build
deleted file mode 100755
index 86c5fc0ae..000000000
--- a/docs/demos/wt/build
+++ /dev/null
@@ -1,341 +0,0 @@
-#!/usr/bin/env python3
-"""Build script for worktrunk demo GIF and text output."""
-
-import os
-import re
-import shutil
-import subprocess
-import sys
-from datetime import datetime, timedelta
-from pathlib import Path
-
-# Add docs/demos/ to path for shared library
-SCRIPT_DIR = Path(__file__).parent
-DEMOS_DIR = SCRIPT_DIR.parent
-sys.path.insert(0, str(DEMOS_DIR))
-
-from lib import DemoEnv, run, git, render_tape, record_vhs, build_wt, REAL_HOME
-from themes import THEMES, format_theme_for_vhs
-
-REPO_ROOT = DEMOS_DIR.parent.parent
-FIXTURES_DIR = SCRIPT_DIR / "fixtures"
-OUT_DIR = SCRIPT_DIR / "out"
-TAPE_TEMPLATE = SCRIPT_DIR / "demo.tape"
-TAPE_RENDERED = OUT_DIR / ".rendered.tape"
-STARSHIP_CONFIG = OUT_DIR / "starship.toml"
-
-# Output GIF paths for light and dark variants
-OUTPUT_GIFS = {
- "light": OUT_DIR / "wt-demo.gif",
- "dark": OUT_DIR / "wt-demo-dark.gif",
-}
-
-
-def commit_dated(repo, message, offset):
- """Commit with a date offset like '7d' or '2H'."""
- now = datetime.now()
- if offset.endswith("d"):
- delta = timedelta(days=int(offset[:-1]))
- elif offset.endswith("H"):
- delta = timedelta(hours=int(offset[:-1]))
- else:
- raise ValueError(f"Unknown offset format: {offset}")
-
- date_str = (now - delta).strftime("%Y-%m-%dT%H:%M:%S")
- env = os.environ.copy()
- env["GIT_AUTHOR_DATE"] = date_str
- env["GIT_COMMITTER_DATE"] = date_str
- env["SKIP_DEMO_HOOK"] = "1"
- git(["-C", str(repo), "commit", "-qm", message], env=env)
-
-
-def prepare_repo(env: DemoEnv):
- """Set up the demo repository with branches and worktrees."""
- # Clean previous
- shutil.rmtree(env.root, ignore_errors=True)
- legacy = REPO_ROOT / ".demo"
- if legacy.exists():
- shutil.rmtree(legacy)
-
- env.root.mkdir(parents=True)
- env.work_base.mkdir(parents=True)
- env.repo.mkdir(parents=True)
-
- # Init bare remote
- run(["git", "init", "--bare", "-q", str(env.bare_remote)])
-
- # Init main repo
- git(["-C", str(env.repo), "init", "-q"])
- git(["-C", str(env.repo), "config", "user.name", "Worktrunk Demo"])
- git(["-C", str(env.repo), "config", "user.email", "[email protected]"])
- git(["-C", str(env.repo), "config", "commit.gpgsign", "false"])
-
- # Initial commit
- (env.repo / "README.md").write_text("# Worktrunk demo\n\nThis repo is generated automatically.\n")
- git(["-C", str(env.repo), "add", "README.md"])
- commit_dated(env.repo, "Initial demo commit", "7d")
- git(["-C", str(env.repo), "branch", "-m", "main"])
- git(["-C", str(env.repo), "remote", "add", "origin", str(env.bare_remote)])
- git(["-C", str(env.repo), "push", "-u", "origin", "main", "-q"])
-
- # Rust project
- (env.repo / "Cargo.toml").write_text(
- "[package]\nname = \"acme\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n[workspace]\n"
- )
- (env.repo / "src").mkdir()
- shutil.copy(FIXTURES_DIR / "lib.rs", env.repo / "src" / "lib.rs")
- (env.repo / ".gitignore").write_text("/target\n")
- git(["-C", str(env.repo), "add", ".gitignore", "Cargo.toml", "src/"])
- commit_dated(env.repo, "Add Rust project with tests", "6d")
-
- # Build to create Cargo.lock
- run(["cargo", "build", "--release", "-q"], cwd=env.repo, check=False)
- git(["-C", str(env.repo), "add", "Cargo.lock"])
- commit_dated(env.repo, "Add Cargo.lock", "6d")
- git(["-C", str(env.repo), "push", "-q"])
-
- # Project hooks
- (env.repo / ".config").mkdir()
- (env.repo / ".config" / "wt.toml").write_text(
- '[pre-merge]\ntest = "cargo nextest run"\n'
- )
- git(["-C", str(env.repo), "add", ".config/wt.toml"])
- commit_dated(env.repo, "Add project hooks", "5d")
- git(["-C", str(env.repo), "push", "-q"])
-
- # Mock gh CLI
- bin_dir = env.home / "bin"
- bin_dir.mkdir(parents=True, exist_ok=True)
- gh_mock = bin_dir / "gh"
- shutil.copy(FIXTURES_DIR / "gh-mock.sh", gh_mock)
- gh_mock.chmod(0o755)
-
- # Build wt binary
- build_wt(REPO_ROOT)
-
- # User config
- config_dir = env.home / ".config" / "worktrunk"
- config_dir.mkdir(parents=True)
- project_id = str(env.bare_remote).removesuffix(".git")
- (config_dir / "config.toml").write_text(f'''[commit-generation]
-command = "llm"
-args = ["-m", "claude-haiku-4.5"]
-
-[projects."{project_id}"]
-approved-commands = ["cargo nextest run"]
-''')
-
- # Extra branches (no worktrees)
- git(["-C", str(env.repo), "branch", "docs/readme"])
- git(["-C", str(env.repo), "branch", "spike/search"])
-
- # Create feature branches
- create_branch_alpha(env)
- create_branch_beta(env)
-
- # Commit to main after beta so beta is behind
- readme = env.repo / "README.md"
- readme.write_text(readme.read_text() + "# Development\nSee CONTRIBUTING.md for guidelines.\n")
- (env.repo / "notes.md").write_text("# Notes\n")
- git(["-C", str(env.repo), "add", "README.md", "notes.md"])
- commit_dated(env.repo, "docs: add development section", "1d")
- git(["-C", str(env.repo), "push", "-q"])
-
- create_branch_hooks(env)
-
-
-def create_branch_alpha(env: DemoEnv):
- """Create alpha branch with large diff and unpushed commits."""
- branch = "alpha"
- path = env.work_base / f"acme.{branch}"
-
- git(["-C", str(env.repo), "checkout", "-q", "-b", branch, "main"])
-
- # Initial README changes
- (env.repo / "README.md").write_text('''# Worktrunk demo
-
-A demo repository for showcasing worktrunk features.
-
-## Features
-
-- Fast worktree switching
-- Integrated merge workflow
-- Pre-merge test hooks
-- LLM commit messages
-
-## Getting Started
-
-Run `wt list` to see all worktrees.
-''')
- git(["-C", str(env.repo), "add", "README.md"])
- commit_dated(env.repo, "docs: expand README", "3d")
-
- # More commits
- readme = env.repo / "README.md"
- readme.write_text(readme.read_text() + "\n# Contributing\nPRs welcome!\n")
- git(["-C", str(env.repo), "add", "README.md"])
- commit_dated(env.repo, "docs: add contributing section", "3d")
-
- readme.write_text(readme.read_text() + "\n# License\nMIT\n")
- git(["-C", str(env.repo), "add", "README.md"])
- commit_dated(env.repo, "docs: add license", "3d")
-
- git(["-C", str(env.repo), "push", "-u", "origin", branch, "-q"])
- git(["-C", str(env.repo), "checkout", "-q", "main"])
- git(["-C", str(env.repo), "worktree", "add", "-q", str(path), branch])
-
- # Unpushed commit
- readme = path / "README.md"
- readme.write_text(readme.read_text() + "# FAQ\n")
- git(["-C", str(path), "add", "README.md"])
- commit_dated(path, "docs: add FAQ section", "3d")
-
- # Working tree changes - large diff
- shutil.copy(FIXTURES_DIR / "alpha-readme.md", path / "README.md")
- (path / "scratch.rs").write_text("// scratch\n")
-
-
-def create_branch_beta(env: DemoEnv):
- """Create beta branch with staged changes."""
- branch = "beta"
- path = env.work_base / f"acme.{branch}"
-
- git(["-C", str(env.repo), "checkout", "-q", "-b", branch, "main"])
- git(["-C", str(env.repo), "push", "-u", "origin", branch, "-q"])
- git(["-C", str(env.repo), "checkout", "-q", "main"])
- git(["-C", str(env.repo), "worktree", "add", "-q", str(path), branch])
-
- # Staged new file
- (path / "notes.txt").write_text("# TODO\n- Add caching\n")
- git(["-C", str(path), "add", "notes.txt"])
-
-
-def create_branch_hooks(env: DemoEnv):
- """Create hooks branch with refactored lib.rs."""
- branch = "hooks"
- path = env.work_base / f"acme.{branch}"
-
- git(["-C", str(env.repo), "checkout", "-q", "-b", branch, "main"])
- shutil.copy(FIXTURES_DIR / "lib-hooks.rs", env.repo / "src" / "lib.rs")
- git(["-C", str(env.repo), "add", "src/lib.rs"])
- commit_dated(env.repo, "feat: add math operations, consolidate tests", "2H")
-
- # No push - no upstream
- git(["-C", str(env.repo), "checkout", "-q", "main"])
- git(["-C", str(env.repo), "worktree", "add", "-q", str(path), branch])
-
- # Staged then modified
- lib_rs = path / "src" / "lib.rs"
- lib_rs.write_text(lib_rs.read_text() + "// Division coming soon\n")
- git(["-C", str(path), "add", "src/lib.rs"])
- lib_rs.write_text(lib_rs.read_text() + "// TODO: add division\n")
-
-
-def record_text(demo_env: DemoEnv):
- """Record text output by running demo commands."""
- # Extract commands from tape
- commands = []
- for line in TAPE_TEMPLATE.read_text().splitlines():
- if line.startswith("Type "):
- cmd = line[5:].strip().strip('"').strip("'")
- # Skip setup commands (fish uses 'set -gx' instead of 'export')
- if not any(cmd.startswith(p) for p in ["set -gx", "export ", "eval ", "cd ", "clear", "exit", "starship init", "wt config shell init"]):
- commands.append(cmd)
-
- # Set up environment
- env = os.environ.copy()
- env.update({
- "LANG": "en_US.UTF-8",
- "LC_ALL": "en_US.UTF-8",
- "COLUMNS": "160",
- "RUSTUP_HOME": str(REAL_HOME / ".rustup"),
- "CARGO_HOME": str(REAL_HOME / ".cargo"),
- "HOME": str(demo_env.home),
- "PATH": f"{REPO_ROOT}/target/debug:{demo_env.home}/bin:{os.environ['PATH']}",
- "STARSHIP_CONFIG": str(STARSHIP_CONFIG),
- "STARSHIP_CACHE": str(demo_env.root / "starship-cache"),
- "NO_COLOR": "1",
- "CLICOLOR": "0",
- "NEXTEST_STATUS_LEVEL": "none",
- "NEXTEST_FINAL_STATUS_LEVEL": "flaky",
- "NEXTEST_NO_FAIL_FAST": "1",
- })
-
- (demo_env.root / "starship-cache").mkdir(exist_ok=True)
-
- # Run commands and capture output using fish with shell init
- script = '''wt config shell init fish | source
-'''
- for cmd in commands:
- script += f'{cmd}\n'
- if cmd.startswith("wt merge"):
- script += 'sleep 2\n'
-
- result = subprocess.run(
- ["fish", "-c", script],
- cwd=demo_env.repo, env=env,
- capture_output=True, text=True
- )
- output = [result.stdout + result.stderr]
-
- # Clean output
- raw = "".join(output)
- clean = re.sub(r"\x1B\[[0-9;?]*[A-Za-z]", "", raw) # Strip ANSI
- clean = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]", "", clean) # Strip control chars
- clean = clean.replace("^D", "")
-
- (OUT_DIR / "run.txt").write_text(clean)
-
-
-def main():
- # Check dependencies
- for cmd in ["wt", "vhs", "starship"]:
- if not shutil.which(cmd):
- raise SystemExit(f"Missing dependency: {cmd}")
-
- OUT_DIR.mkdir(parents=True, exist_ok=True)
-
- # Copy starship config
- shutil.copy(FIXTURES_DIR / "starship.toml", STARSHIP_CONFIG)
-
- # Create separate environments for text and VHS recording
- # so they don't interfere with each other (different LLM-generated commits)
- text_env = DemoEnv(name="text", out_dir=OUT_DIR, repo_name="acme")
- vhs_env = DemoEnv(name="vhs", out_dir=OUT_DIR, repo_name="acme")
-
- prepare_repo(text_env)
- record_text(text_env)
-
- prepare_repo(vhs_env)
-
- # Record both light and dark variants
- docs_assets = REPO_ROOT / "docs" / "static" / "assets"
- docs_assets.mkdir(parents=True, exist_ok=True)
-
- for theme_name, output_gif in OUTPUT_GIFS.items():
- theme = THEMES[theme_name]
- replacements = {
- "DEMO_REPO": vhs_env.repo,
- "DEMO_HOME": vhs_env.home,
- "REAL_HOME": REAL_HOME,
- "STARSHIP_CONFIG": STARSHIP_CONFIG,
- "OUTPUT_GIF": output_gif,
- "TARGET_DEBUG": REPO_ROOT / "target" / "debug",
- "THEME": format_theme_for_vhs(theme),
- }
- render_tape(TAPE_TEMPLATE, TAPE_RENDERED, replacements)
- print(f"\nRecording {theme_name} GIF...")
- record_vhs(TAPE_RENDERED)
- TAPE_RENDERED.unlink(missing_ok=True)
- print(f"GIF saved to {output_gif}")
-
- # Copy to docs for local preview
- asset_name = output_gif.name
- shutil.copy(output_gif, docs_assets / asset_name)
- print(f"Copied to {docs_assets / asset_name}")
-
- print(f"\nText log saved to {OUT_DIR / 'run.txt'}")
-
-
-if __name__ == "__main__":
- main()
diff --git a/docs/demos/wt/fixtures/starship.toml b/docs/demos/wt/fixtures/starship.toml
deleted file mode 100644
index f6b1fe3e0..000000000
--- a/docs/demos/wt/fixtures/starship.toml
+++ /dev/null
@@ -1,47 +0,0 @@
-format = "$directory$character"
-palette = "gh_light"
-
-[palettes.gh_light]
-fg = "#1f2328"
-bg = "#ffffff"
-blue = "#0969da"
-yellow = "#d29922"
-green = "#2ea043"
-red = "#d73a49"
-muted = "#57606a"
-gold = "#d97706"
-
-[directory]
-style = "bold fg:gold"
-truncation_length = 3
-truncate_to_repo = true
-home_symbol = "~"
-
-[git_branch]
-style = "fg:muted"
-symbol = " "
-format = " [$symbol$branch]($style)"
-
-[git_status]
-style = "fg:red"
-format = " [$all_status$ahead_behind]($style)"
-conflicted = "โ‡•"
-ahead = "โ‡ก"
-behind = "โ‡ฃ"
-staged = "+"
-modified = "!"
-untracked = "?"
-
-[cmd_duration]
-min_time = 500
-# Keep duration but drop the timer icon to reduce prompt noise.
-format = " [$duration]($style)"
-style = "fg:muted"
-
-[character]
-success_symbol = "[โฏ](fg:gold)"
-error_symbol = "[โฏ](fg:red)"
-vicmd_symbol = "[โฎ](fg:gold)"
-
-[time]
-disabled = true
diff --git a/src/cli.rs b/src/cli.rs
index de86d4eff..7fe7699ab 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -2298,7 +2298,9 @@ Removal runs in the background by default (returns immediately). Logs are writte
/// Merge worktree into target branch
///
/// Squashes commits, rebases, runs hooks, merges to target, and removes the worktree.
- #[command(after_long_help = r#"## Examples
+ #[command(after_long_help = r#"<!-- demo: wt-merge.gif 1600x900 -->
+
+## Examples
Basic merge to main:
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 221584051..3c79b7d10 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
@@ -9,6 +9,7 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
---
@@ -67,6 +68,8 @@ Global Options:
-v, --verbose
Show commands and debug info
+<!-- demo: wt-merge.gif 1600x900 -->
+
## Examples
Basic merge to main:
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 62f63854f..f4f67ca23 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -9,6 +9,7 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
---
@@ -69,6 +70,7 @@ Usage: wt merge [OPTIONS] [TARGET]
-v, --verbose
Show commands and debug info
+
Examples
Basic merge to main:
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_merge.snap b/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
index be30d41c3..8eefae516 100644
--- a/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
@@ -9,6 +9,7 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
---
@@ -17,6 +18,13 @@ exit_code: 0
----- stdout -----
<!-- โš ๏ธ AUTO-GENERATED from `wt merge --help-page` โ€” edit cli.rs to update -->
+<figure class="demo">
+<picture>
+ <source srcset="/assets/wt-merge-dark.gif" media="(prefers-color-scheme: dark)">
+ <img src="/assets/wt-merge.gif" alt="wt merge demo" width="1600" height="900">
+</picture>
+</figure>
+
## Examples
Basic merge to main: