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.mdindex 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.mdindex 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.mdindex 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 validationQuick checks before commit, thorough validation before merge:@@ -470,6 +411,11 @@ kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dremove-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 mergediff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.mdindex 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.mdindex 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.mdindex 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 validationQuick checks before commit, thorough validation before merge:@@ -471,6 +410,11 @@ kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dremove-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.mdindex 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.rsindex 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 validationQuick checks before commit, thorough validation before merge:@@ -1612,6 +1551,11 @@ kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dremove-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 mergediff --git a/src/help.rs b/src/help.rsindex 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).