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.mdindex 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.mdindex 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 + agentCreate 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.mdindex 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.mdindex 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 + agentCreate 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.mdindex 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: