Skip to content

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

docs(hook): link dev-server/database recipes out to tips-patterns (#2319)

Maximilian Roosdf448861bc01
diff --git a/README.md b/README.md
index 7b59830a0..11c3bca9d 100644
--- a/README.md
+++ b/README.md
@@ -90,7 +90,7 @@ git branch -d feat</pre></td>
- **[Copy build caches](https://worktrunk.dev/step/#wt-step-copy-ignored)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees
- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch
- **[PR checkout](https://worktrunk.dev/switch/#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch
-- **[Dev server per worktree](https://worktrunk.dev/hook/#dev-servers)** — `hash_port` template filter gives each worktree a unique port
+- **[Dev server per worktree](https://worktrunk.dev/tips-patterns/#dev-server-per-worktree)** — `hash_port` template filter gives each worktree a unique port
- **[Aliases](https://worktrunk.dev/extending/#aliases) & [per-branch variables](https://worktrunk.dev/config/#wt-config-state-vars)** — custom `wt <name>` commands and branch-scoped state for hook templates
- ...and **[lots more](#next-steps)**
diff --git a/docs/content/extending.md b/docs/content/extending.md
index 7a76fdbca..edc2395b9 100644
--- a/docs/content/extending.md
+++ b/docs/content/extending.md
@@ -69,7 +69,7 @@ since-main = "git log --oneline {{ default_branch }}..HEAD"
### Templates
-Alias templates have access to the full [variable and filter reference](@/hook.md#template-variables), plus `{{ args }}` for positional CLI arguments. Operation-context variables (`target`, `base`, `pr_number`) aren't populated in aliases since there's no operation in progress.
+Alias templates have access to the full [variable and filter reference](@/hook.md#template-variables), plus `{{ args }}` for positional CLI arguments. Operation-context variables (`target`, `base`, `pr_number`) aren't auto-populated in aliases since there's no operation in progress — but any of them can still be bound on the CLI with `--KEY=VALUE`.
`--KEY=VALUE` (or `--KEY VALUE`) binds `KEY` whenever `{{ KEY }}` appears in the template — `wt deploy --env=staging` sets `{{ env }}` to `staging`. Everything else joins `{{ args }}` (see [Positional arguments](#positional-arguments)).
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 9de39f220..603867f6a 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -329,65 +329,6 @@ copy = "wt step copy-ignored"
install = "pnpm install"
```
-## Dev servers
-
-Run a dev server per worktree on a deterministic port using `hash_port`:
-
-```toml
-[post-start]
-server = "npm run dev -- --port {{ branch | hash_port }}"
-
-[post-remove]
-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/null || true"
-```
-
-The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`:
-
-```toml
-[list]
-url = "http://localhost:{{ branch | hash_port }}"
-```
-
-For subdomain-based routing (useful for cookies/CORS), use `.localhost` subdomains which resolve to 127.0.0.1:
-
-```toml
-[post-start]
-server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branch | hash_port }}"
-```
-
-## Databases
-
-Each worktree can have its own database. A pipeline sets up the container name and connection string as vars, then later steps and hooks reference them:
-
-```toml
-[[post-start]]
-set-vars = """
-wt config state vars set \
- container='{{ repo }}-{{ branch | sanitize }}-postgres' \
- port='{{ ('db-' ~ branch) | hash_port }}' \
- db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'
-"""
-
-[[post-start]]
-db = """
-docker run -d --rm \
- --name {{ vars.container }} \
- -p {{ vars.port }}:5432 \
- -e POSTGRES_DB={{ branch | sanitize_db }} \
- -e POSTGRES_PASSWORD=dev \
- postgres:16
-"""
-
-[post-remove]
-db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"
-```
-
-The first pipeline step derives names and ports from the branch name and stores them as vars. The second step uses `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. The `post-remove` hook reads the same vars.
-
-The connection string is accessible anywhere — not just in hooks:
-
-{{ terminal(cmd="DATABASE_URL=$(wt config state vars get db_url) npm start") }}
-
## Progressive validation
Quick checks before commit, thorough validation before merge:
@@ -470,6 +411,11 @@ kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/d
remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
```
+## More recipes
+
+- Dev server per worktree: `hash_port` in `post-start` for launch and `post-remove` for cleanup, with optional subdomain routing — see [Tips & Patterns](@/tips-patterns.md#dev-server-per-worktree)
+- Database per worktree: a `post-start` pipeline stores container name, port, and connection string as [per-branch vars](@/config.md#wt-config-state-vars) that later hooks reference — see [Tips & Patterns](@/tips-patterns.md#database-per-worktree)
+
## See also
- [`wt merge`](@/merge.md) — Runs hooks automatically during merge
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index e7273c1d9..be03f99ba 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -90,7 +90,7 @@ git branch -d feat{% end %}</td>
- **[Copy build caches](@/step.md#wt-step-copy-ignored)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees
- **[`wt list --full`](@/list.md#full-mode)** — [CI status](@/list.md#ci-status) and [AI-generated summaries](@/list.md#llm-summaries) per branch
- **[PR checkout](@/switch.md#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch
-- **[Dev server per worktree](@/hook.md#dev-servers)** — `hash_port` template filter gives each worktree a unique port
+- **[Dev server per worktree](@/tips-patterns.md#dev-server-per-worktree)** — `hash_port` template filter gives each worktree a unique port
- **[Aliases](@/extending.md#aliases) & [per-branch variables](@/config.md#wt-config-state-vars)** — custom `wt <name>` commands and branch-scoped state for hook templates
- ...and **[lots more](#next-steps)**
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index 2ef1486f8..3cf50ffd4 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -65,7 +65,7 @@ wt open
### Templates
-Alias templates have access to the full [variable and filter reference](https://worktrunk.dev/hook/#template-variables), plus `{{ args }}` for positional CLI arguments. Operation-context variables (`target`, `base`, `pr_number`) aren't populated in aliases since there's no operation in progress.
+Alias templates have access to the full [variable and filter reference](https://worktrunk.dev/hook/#template-variables), plus `{{ args }}` for positional CLI arguments. Operation-context variables (`target`, `base`, `pr_number`) aren't auto-populated in aliases since there's no operation in progress — but any of them can still be bound on the CLI with `--KEY=VALUE`.
`--KEY=VALUE` (or `--KEY VALUE`) binds `KEY` whenever `{{ KEY }}` appears in the template — `wt deploy --env=staging` sets `{{ env }}` to `staging`. Everything else joins `{{ args }}` (see [Positional arguments](#positional-arguments)).
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 48fd2c950..f435527aa 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -328,67 +328,6 @@ copy = "wt step copy-ignored"
install = "pnpm install"
```
-## Dev servers
-
-Run a dev server per worktree on a deterministic port using `hash_port`:
-
-```toml
-[post-start]
-server = "npm run dev -- --port {{ branch | hash_port }}"
-
-[post-remove]
-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/null || true"
-```
-
-The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`:
-
-```toml
-[list]
-url = "http://localhost:{{ branch | hash_port }}"
-```
-
-For subdomain-based routing (useful for cookies/CORS), use `.localhost` subdomains which resolve to 127.0.0.1:
-
-```toml
-[post-start]
-server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branch | hash_port }}"
-```
-
-## Databases
-
-Each worktree can have its own database. A pipeline sets up the container name and connection string as vars, then later steps and hooks reference them:
-
-```toml
-[[post-start]]
-set-vars = """
-wt config state vars set \
- container='{{ repo }}-{{ branch | sanitize }}-postgres' \
- port='{{ ('db-' ~ branch) | hash_port }}' \
- db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'
-"""
-
-[[post-start]]
-db = """
-docker run -d --rm \
- --name {{ vars.container }} \
- -p {{ vars.port }}:5432 \
- -e POSTGRES_DB={{ branch | sanitize_db }} \
- -e POSTGRES_PASSWORD=dev \
- postgres:16
-"""
-
-[post-remove]
-db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"
-```
-
-The first pipeline step derives names and ports from the branch name and stores them as vars. The second step uses `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. The `post-remove` hook reads the same vars.
-
-The connection string is accessible anywhere — not just in hooks:
-
-```bash
-$ DATABASE_URL=$(wt config state vars get db_url) npm start
-```
-
## Progressive validation
Quick checks before commit, thorough validation before merge:
@@ -471,6 +410,11 @@ kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/d
remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
```
+## More recipes
+
+- Dev server per worktree: `hash_port` in `post-start` for launch and `post-remove` for cleanup, with optional subdomain routing — https://worktrunk.dev/tips-patterns/#dev-server-per-worktree
+- Database per worktree: a `post-start` pipeline stores container name, port, and connection string as [per-branch vars](https://worktrunk.dev/config/#wt-config-state-vars) that later hooks reference — https://worktrunk.dev/tips-patterns/#database-per-worktree
+
## Command reference
```
diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.md
index 104f5d86d..2d43f4809 100644
--- a/skills/worktrunk/reference/worktrunk.md
+++ b/skills/worktrunk/reference/worktrunk.md
@@ -75,7 +75,7 @@ git branch -d feat</td>
- **[Copy build caches](https://worktrunk.dev/step/#wt-step-copy-ignored)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees
- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch
- **[PR checkout](https://worktrunk.dev/switch/#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch
-- **[Dev server per worktree](https://worktrunk.dev/hook/#dev-servers)** — `hash_port` template filter gives each worktree a unique port
+- **[Dev server per worktree](https://worktrunk.dev/tips-patterns/#dev-server-per-worktree)** — `hash_port` template filter gives each worktree a unique port
- **[Aliases](https://worktrunk.dev/extending/#aliases) & [per-branch variables](https://worktrunk.dev/config/#wt-config-state-vars)** — custom `wt <name>` commands and branch-scoped state for hook templates
- ...and **[lots more](#next-steps)**
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 3e68417fb..a995db214 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1469,67 +1469,6 @@ copy = "wt step copy-ignored"
install = "pnpm install"
```
-## Dev servers
-
-Run a dev server per worktree on a deterministic port using `hash_port`:
-
-```toml
-[post-start]
-server = "npm run dev -- --port {{ branch | hash_port }}"
-
-[post-remove]
-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/null || true"
-```
-
-The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`:
-
-```toml
-[list]
-url = "http://localhost:{{ branch | hash_port }}"
-```
-
-For subdomain-based routing (useful for cookies/CORS), use `.localhost` subdomains which resolve to 127.0.0.1:
-
-```toml
-[post-start]
-server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branch | hash_port }}"
-```
-
-## Databases
-
-Each worktree can have its own database. A pipeline sets up the container name and connection string as vars, then later steps and hooks reference them:
-
-```toml
-[[post-start]]
-set-vars = """
-wt config state vars set \
- container='{{ repo }}-{{ branch | sanitize }}-postgres' \
- port='{{ ('db-' ~ branch) | hash_port }}' \
- db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'
-"""
-
-[[post-start]]
-db = """
-docker run -d --rm \
- --name {{ vars.container }} \
- -p {{ vars.port }}:5432 \
- -e POSTGRES_DB={{ branch | sanitize_db }} \
- -e POSTGRES_PASSWORD=dev \
- postgres:16
-"""
-
-[post-remove]
-db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"
-```
-
-The first pipeline step derives names and ports from the branch name and stores them as vars. The second step uses `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. The `post-remove` hook reads the same vars.
-
-The connection string is accessible anywhere — not just in hooks:
-
-```console
-$ DATABASE_URL=$(wt config state vars get db_url) npm start
-```
-
## Progressive validation
Quick checks before commit, thorough validation before merge:
@@ -1612,6 +1551,11 @@ kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/d
remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
```
+## More recipes
+
+- Dev server per worktree: `hash_port` in `post-start` for launch and `post-remove` for cleanup, with optional subdomain routing — https://worktrunk.dev/tips-patterns/#dev-server-per-worktree
+- Database per worktree: a `post-start` pipeline stores container name, port, and connection string as [per-branch vars](@/config.md#wt-config-state-vars) that later hooks reference — https://worktrunk.dev/tips-patterns/#database-per-worktree
+
## See also
- [`wt merge`](@/merge.md) — Runs hooks automatically during merge
diff --git a/src/help.rs b/src/help.rs
index 4545f6ec8..2d3d8b563 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -526,6 +526,16 @@ fn post_process_for_html(text: &str) -> String {
"Open an issue at https://github.com/max-sixty/worktrunk.",
"[Open an issue](https://github.com/max-sixty/worktrunk/issues).",
)
+ // Tips & Patterns recipe bullets: bare URLs (terminal auto-links) in CLI,
+ // inline markdown links on the web.
+ .replace(
+ "routing — https://worktrunk.dev/tips-patterns/#dev-server-per-worktree",
+ "routing — see [Tips & Patterns](@/tips-patterns.md#dev-server-per-worktree)",
+ )
+ .replace(
+ "hooks reference — https://worktrunk.dev/tips-patterns/#database-per-worktree",
+ "hooks reference — see [Tips & Patterns](@/tips-patterns.md#database-per-worktree)",
+ )
// Approval prompt: plain code block → terminal shortcode with colored symbols
// and gutter. CLI shows a plain ``` block; web shows styled terminal output
// matching the actual CLI appearance (yellow ▲, dim ○, cyan ❯, gutter bar).