Skip to content

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

docs: surface vars & aliases on homepage and tips-patterns (#2038)

Maximilian Roos71499df45b70
diff --git a/README.md b/README.md
index c81cb28a4..a72133eb6 100644
--- a/README.md
+++ b/README.md
@@ -91,6 +91,7 @@ git branch -d feat</pre></td>
- **[`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
+- **[Aliases](https://worktrunk.dev/step/#aliases) & [per-branch variables](https://worktrunk.dev/config/#wt-config-state-vars)** — custom `wt step <name>` commands and branch-scoped state for hook templates
- ...and **[lots more](#next-steps)**
A demo with some advanced features:
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 539bf9de0..09fd3dcf4 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -9,24 +9,37 @@ group = "Reference"
Practical recipes for common Worktrunk workflows.
-## Alias for new worktree + agent
+## Shell alias for new worktree + agent
Create a worktree and launch Claude in one command:
{{ terminal(cmd="alias wsc='wt switch --create --execute=claude'|||wsc new-feature # Creates worktree, runs hooks, launches Claude|||wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`") }}
-## Eliminate cold starts
+## `wt` aliases
-Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) to copy gitignored files (caches, dependencies, `.env`) between worktrees:
+Compose with template filters and [vars](@/tips-patterns.md#per-branch-variables) for branch-specific shortcuts:
```toml
-[post-start]
-copy = "wt step copy-ignored"
+# .config/wt.toml
+[aliases]
+# Open this worktree's dev server
+open = "open http://localhost:{{ branch | hash_port }}"
+
+# Test with branch-specific features from vars
+test = "cargo test --features {{ vars.features | default('default') }}"
```
-Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.
+See [`wt step` aliases](@/step.md#aliases) for scoping, approval, and reference.
-All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) for details.
+## Per-branch variables
+
+`wt config state vars` holds state per branch, accessible from templates (`{{ vars.key }}`) and the CLI. Some uses:
+
+- **Coordinate state across pipeline steps** — see [Database per worktree](@/tips-patterns.md#database-per-worktree) below for a full recipe
+- **Stick a branch to an environment** — `wt config state vars set env=staging`, then `{{ vars.env | default('dev') }}` in hooks
+- **Parametrize aliases per branch** — see [`wt` aliases above](@/tips-patterns.md#wt-aliases)
+
+See [`wt config state vars`](@/config.md#wt-config-state-vars) for storage format, JSON support, and reference.
## Dev server per worktree
@@ -97,6 +110,19 @@ The connection string is accessible anywhere — not just in hooks:
{{ terminal(cmd="DATABASE_URL=$(wt config state vars get db_url) npm start") }}
+## Eliminate cold starts
+
+Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) to copy gitignored files (caches, dependencies, `.env`) between worktrees:
+
+```toml
+[post-start]
+copy = "wt step copy-ignored"
+```
+
+Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.
+
+All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) for details.
+
## Local CI gate
`pre-merge` hooks run before merging. Failures abort the merge:
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index fb41f18b0..9ea673899 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -91,6 +91,7 @@ git branch -d feat{% end %}</td>
- **[`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
+- **[Aliases](@/step.md#aliases) & [per-branch variables](@/config.md#wt-config-state-vars)** — custom `wt step <name>` commands and branch-scoped state for hook templates
- ...and **[lots more](#next-steps)**
A demo with some advanced features:
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index 98900e207..64c7a696b 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -2,7 +2,7 @@
Practical recipes for common Worktrunk workflows.
-## Alias for new worktree + agent
+## Shell alias for new worktree + agent
Create a worktree and launch Claude in one command:
@@ -12,18 +12,31 @@ $ wsc new-feature # Creates worktree, runs hooks, launches
$ wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`
```
-## Eliminate cold starts
+## `wt` aliases
-Use [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) to copy gitignored files (caches, dependencies, `.env`) between worktrees:
+Compose with template filters and [vars](https://worktrunk.dev/tips-patterns/#per-branch-variables) for branch-specific shortcuts:
```toml
-[post-start]
-copy = "wt step copy-ignored"
+# .config/wt.toml
+[aliases]
+# Open this worktree's dev server
+open = "open http://localhost:{{ branch | hash_port }}"
+
+# Test with branch-specific features from vars
+test = "cargo test --features {{ vars.features | default('default') }}"
```
-Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.
+See [`wt step` aliases](https://worktrunk.dev/step/#aliases) for scoping, approval, and reference.
-All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) for details.
+## Per-branch variables
+
+`wt config state vars` holds state per branch, accessible from templates (`{{ vars.key }}`) and the CLI. Some uses:
+
+- **Coordinate state across pipeline steps** — see [Database per worktree](https://worktrunk.dev/tips-patterns/#database-per-worktree) below for a full recipe
+- **Stick a branch to an environment** — `wt config state vars set env=staging`, then `{{ vars.env | default('dev') }}` in hooks
+- **Parametrize aliases per branch** — see [`wt` aliases above](https://worktrunk.dev/tips-patterns/#wt-aliases)
+
+See [`wt config state vars`](https://worktrunk.dev/config/#wt-config-state-vars) for storage format, JSON support, and reference.
## Dev server per worktree
@@ -92,6 +105,19 @@ The connection string is accessible anywhere — not just in hooks:
$ DATABASE_URL=$(wt config state vars get db_url) npm start
```
+## Eliminate cold starts
+
+Use [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) to copy gitignored files (caches, dependencies, `.env`) between worktrees:
+
+```toml
+[post-start]
+copy = "wt step copy-ignored"
+```
+
+Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.
+
+All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) for details.
+
## Local CI gate
`pre-merge` hooks run before merging. Failures abort the merge:
diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.md
index 681b96638..0dee34400 100644
--- a/skills/worktrunk/reference/worktrunk.md
+++ b/skills/worktrunk/reference/worktrunk.md
@@ -76,6 +76,7 @@ git branch -d feat</td>
- **[`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
+- **[Aliases](https://worktrunk.dev/step/#aliases) & [per-branch variables](https://worktrunk.dev/config/#wt-config-state-vars)** — custom `wt step <name>` commands and branch-scoped state for hook templates
- ...and **[lots more](#next-steps)**
A demo with some advanced features: