Skip to content

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

docs: add demo GIFs to command pages (#324)

Maximilian Roos5dac49806afa
diff --git a/.config/lychee.toml b/.config/lychee.toml
index ef201f5a7..5708cb0c7 100644
--- a/.config/lychee.toml
+++ b/.config/lychee.toml
@@ -47,7 +47,7 @@ exclude = [
# Asset GIFs stored in separate worktrunk-assets repo (gitignored, fetched at deploy)
# Pattern for file:// URLs and root-relative paths
"file://.*wt-.*\\.gif",
- "/assets/wt-.*\\.gif",
+ "/assets/.*\\.gif",
# Local build artifacts (not checked into git)
"wt-demo/out/wt-demo\\.gif",
@@ -64,12 +64,4 @@ exclude = [
# Exclude source files from link checking
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",
- # README references assets that may not be published yet
- "README.md",
]
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index ee452655c..7f2dc85bd 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -24,6 +24,8 @@ jobs:
uses: baptiste0928/cargo-install@v3
with:
crate: lychee
+ # Pin to 0.20.x - 0.22.0 has a regression with exclude patterns for root-relative paths
+ version: ^0.20
- name: πŸ” Pre-commit hooks
uses: pre-commit/[email protected]
@@ -89,6 +91,8 @@ jobs:
uses: baptiste0928/cargo-install@v3
with:
crate: lychee
+ # Pin to 0.20.x - 0.22.0 has a regression with exclude patterns for root-relative paths
+ version: ^0.20
- name: Install wt
uses: baptiste0928/cargo-install@v3
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.md
index d23dfd2b1..bd3e458a9 100644
--- a/docs/content/claude-code.md
+++ b/docs/content/claude-code.md
@@ -53,6 +53,13 @@ $ git config worktrunk.state.feature.marker '{"marker":"πŸ’¬","set_at":0}' # Di
<code>~/w/myproject.feature-auth !πŸ€– @<span style='color:#0a0'>+42</span> <span style='color:#a00'>-8</span> <span style='color:#0a0'>↑3</span> <span style='color:#0a0'>⇑1</span> <span style='color:#0a0'>●</span> | Opus</code>
+<figure class="demo">
+<picture>
+ <source srcset="/assets/docs/dark/wt-statusline.gif" media="(prefers-color-scheme: dark)">
+ <img src="/assets/docs/light/wt-statusline.gif" alt="Claude Code statusline demo" width="1600" height="900">
+</picture>
+</figure>
+
Add to `~/.claude/settings.json`:
```json
diff --git a/docs/content/list.md b/docs/content/list.md
index e18afa6d9..998fa082b 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -10,6 +10,13 @@ group = "Commands"
Show all worktrees with their status. The table includes uncommitted changes, divergence from the default branch and remote, and optional CI status.
+<figure class="demo">
+<picture>
+ <source srcset="/assets/docs/dark/wt-list.gif" media="(prefers-color-scheme: dark)">
+ <img src="/assets/docs/light/wt-list.gif" alt="wt list demo" width="1600" height="900">
+</picture>
+</figure>
+
The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. With `--full`, CI status fetches from the network β€” the table displays instantly and CI fills in as results arrive.
## Examples
diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.md
index f6c6ca2c4..2b3d4dd2b 100644
--- a/docs/content/llm-commits.md
+++ b/docs/content/llm-commits.md
@@ -8,6 +8,13 @@ group = "Reference"
Worktrunk generates commit messages by building a templated prompt and piping it to an external command. This integrates with `wt merge`, `wt step commit`, and `wt step squash`.
+<figure class="demo">
+<picture>
+ <source srcset="/assets/docs/dark/wt-commit.gif" media="(prefers-color-scheme: dark)">
+ <img src="/assets/docs/light/wt-commit.gif" alt="LLM commit message generation demo" width="1600" height="900">
+</picture>
+</figure>
+
## Setup
### Install llm
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 9de221a39..942e75f5f 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -8,6 +8,8 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` β€” edit cli.rs to update -->
+Run from a feature worktree to merge into the default branch β€” like clicking "Merge pull request" on GitHub.
+
<figure class="demo">
<picture>
<source srcset="/assets/docs/dark/wt-merge.gif" media="(prefers-color-scheme: dark)">
@@ -15,8 +17,6 @@ group = "Commands"
</picture>
</figure>
-Run from a feature worktree to merge into the default branch β€” like clicking "Merge pull request" on GitHub.
-
## Examples
Merge to the default branch:
diff --git a/docs/content/switch.md b/docs/content/switch.md
index eb3c05987..ac8474075 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -10,6 +10,13 @@ group = "Commands"
Change directory to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
+<figure class="demo">
+<picture>
+ <source srcset="/assets/docs/dark/wt-switch.gif" media="(prefers-color-scheme: dark)">
+ <img src="/assets/docs/light/wt-switch.gif" alt="wt switch demo" width="1600" height="900">
+</picture>
+</figure>
+
Worktrees are addressed by branch name β€” each worktree has exactly one branch, and the path is derived automatically.
## Examples
diff --git a/docs/demos/CLAUDE.md b/docs/demos/CLAUDE.md
index d7ed41088..d6b3f051a 100644
--- a/docs/demos/CLAUDE.md
+++ b/docs/demos/CLAUDE.md
@@ -37,7 +37,7 @@ Regenerate a single demo:
| Target | Demos |
|--------|-------|
-| docs | wt-core, wt-merge, wt-select, wt-zellij-omnibus |
+| docs | wt-core, wt-switch, wt-list, wt-commit, wt-statusline, wt-merge, wt-select, wt-zellij-omnibus |
| social | wt-switch, wt-statusline, wt-list, wt-list-remove, wt-hooks, wt-devserver, wt-commit, wt-merge, wt-select-short, wt-core, wt-zellij-omnibus |
## Publishing demos
diff --git a/docs/demos/build b/docs/demos/build
index 14ffe1889..c6c26caf8 100755
--- a/docs/demos/build
+++ b/docs/demos/build
@@ -257,6 +257,10 @@ echo "Add placeholder module for user profile settings."
DOCS_DEMOS = [
("wt-core.tape", "wt-core", prepare_with_hooks, "vhs"),
+ ("wt-switch.tape", "wt-switch", prepare_switch, "vhs"),
+ ("wt-list.tape", "wt-list", prepare_with_hooks, "vhs"),
+ ("wt-commit.tape", "wt-commit", prepare_merge_demo, "vhs"),
+ ("wt-statusline.tape", "wt-statusline", prepare_switch, "vhs"),
("wt-merge.tape", "wt-merge", prepare_merge_demo, "vhs"),
("wt-select.tape", "wt-select", prepare_basic, "vhs-keystrokes"),
("wt-zellij-omnibus.tape", "wt-zellij-omnibus", prepare_zellij_omnibus, "vhs"),
diff --git a/src/cli.rs b/src/cli.rs
index cb992fbd0..9cd3764d7 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1884,6 +1884,8 @@ Branches without worktrees are included β€” selecting one creates a worktree. (`
#[command(
after_long_help = r#"Show all worktrees with their status. The table includes uncommitted changes, divergence from the default branch and remote, and optional CI status.
+<!-- demo: wt-list.gif 1600x900 -->
+
The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. With `--full`, CI status fetches from the network β€” the table displays instantly and CI fills in as results arrive.
## Examples
@@ -2141,6 +2143,8 @@ When `main_state == "integrated"`: `"ancestor"` `"trees_match"` `"no_added_chang
#[command(
after_long_help = r#"Change directory to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
+<!-- demo: wt-switch.gif 1600x900 -->
+
Worktrees are addressed by branch name β€” each worktree has exactly one branch, and the path is derived automatically.
## Examples
@@ -2351,9 +2355,10 @@ 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#"<!-- demo: wt-merge.gif 1600x900 -->
+ #[command(
+ after_long_help = r#"Run from a feature worktree to merge into the default branch β€” like clicking "Merge pull request" on GitHub.
-Run from a feature worktree to merge into the default branch β€” like clicking "Merge pull request" on GitHub.
+<!-- demo: wt-merge.gif 1600x900 -->
## Examples
@@ -2420,7 +2425,8 @@ lint = "cargo clippy"
- [wt step](@/step.md) β€” Run individual merge steps (commit, squash, rebase, push)
- [wt remove](@/remove.md) β€” Remove worktrees without merging
- [wt switch](@/switch.md) β€” Navigate to other worktrees
-"#)]
+"#
+ )]
Merge {
/// Target branch
///
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index 53eb61f00..7a60f3d01 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -61,6 +61,7 @@ Usage: wt list [OPTIONS]
Show all worktrees with their status. The table includes uncommitted changes, divergence from the default branch and remote, and optional CI status.
+
The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as
background git operations complete. With --full, CI status fetches from the network β€” the table displays instantly and CI fills in as results
arrive.
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index b0534c9fe..d80a87e2c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
@@ -63,6 +63,7 @@ Usage: wt list [OPTIONS]
Show all worktrees with their status. The table includes uncommitted changes,
divergence from the default branch and remote, and optional CI status.
+
The table renders progressively: branch names, paths, and commit hashes appear
immediately, then status, divergence, and other columns fill in as background
git operations complete. With --full, CI status fetches from the network β€” the
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 f9de4a6b0..7cb4a95dd 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
@@ -68,10 +68,10 @@ Global Options:
-v, --verbose
Show commands and debug info
-<!-- demo: wt-merge.gif 1600x900 -->
-
Run from a feature worktree to merge into the default branch β€” like clicking "Merge pull request" on GitHub.
+<!-- demo: wt-merge.gif 1600x900 -->
+
## Examples
Merge to the default branch:
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
index 40affc34c..7f122ae4e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -70,9 +70,9 @@ Usage: wt merge [OPTIONS] [TARGET]
-v, --verbose
Show commands and debug info
-
Run from a feature worktree to merge into the default branch β€” like clicking "Merge pull request" on GitHub.
+
Examples
Merge to the default branch:
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 c1e8175e6..f2e850975 100644
--- a/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
@@ -18,6 +18,8 @@ exit_code: 0
----- stdout -----
<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` β€” edit cli.rs to update -->
+Run from a feature worktree to merge into the default branch β€” like clicking "Merge pull request" on GitHub.
+
<figure class="demo">
<picture>
<source srcset="/assets/docs/dark/wt-merge.gif" media="(prefers-color-scheme: dark)">
@@ -25,8 +27,6 @@ exit_code: 0
</picture>
</figure>
-Run from a feature worktree to merge into the default branch β€” like clicking "Merge pull request" on GitHub.
-
## Examples
Merge to the default branch:
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
index 537f18fc4..d15bde9a7 100644
--- a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
@@ -20,6 +20,13 @@ exit_code: 0
Change directory to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
+<figure class="demo">
+<picture>
+ <source srcset="/assets/docs/dark/wt-switch.gif" media="(prefers-color-scheme: dark)">
+ <img src="/assets/docs/light/wt-switch.gif" alt="wt switch demo" width="1600" height="900">
+</picture>
+</figure>
+
Worktrees are addressed by branch name β€” each worktree has exactly one branch, and the path is derived automatically.
## Examples
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 06bd2fa9a..397f3d125 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -80,6 +80,7 @@ Usage: wt switch [OPTIONS] <BRANCH> [--
Change directory to a worktree, creating one if needed. Creating a worktree runs hooks.
+
Worktrees are addressed by branch name β€” each worktree has exactly one branch, and the path is derived automatically.
Examples