Skip to content

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

feat: lazy template expansion for pipeline vars (#1840)

Maximilian Roos79fa6a8b73ca
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 71497ea5c..a90ebc2b9 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -333,27 +333,33 @@ server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ bran
## Databases
-Each worktree can have its own database. Docker containers get unique names and ports, and the connection string is stored in `vars` for use outside hooks:
+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]
-db = """
-docker run -d --rm \
- --name {{ repo }}-{{ branch | sanitize }}-postgres \
- -p {{ ('db-' ~ branch) | hash_port }}:5432 \
- -e POSTGRES_DB={{ branch | sanitize_db }} \
- -e POSTGRES_PASSWORD=dev \
- postgres:16
-"""
-db-url = "wt config state vars set db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'"
+post-start = [
+ """
+ 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 }}'
+ """,
+ { 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 {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
+db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"
```
-The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.
+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 now accessible anywhere — not just in hooks:
+The connection string is accessible anywhere — not just in hooks:
{{ terminal(cmd="DATABASE_URL=$(wt config state vars get db-url) npm start") }}
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index fc4ca04f6..9d8307d32 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -65,27 +65,35 @@ Ports are deterministic — `fix-auth` always gets port 16460, regardless of whi
## Database per worktree
-Each worktree can have its own isolated database. Docker containers get unique names and ports, and the connection string is stored in `vars` for use outside hooks:
+Each worktree can have its own isolated database. A pipeline sets up names and ports as vars, then later steps and hooks reference them:
```toml
-[post-start]
-db = """
-docker run -d --rm \
- --name {{ repo }}-{{ branch | sanitize }}-postgres \
- -p {{ ('db-' ~ branch) | hash_port }}:5432 \
- -e POSTGRES_DB={{ branch | sanitize_db }} \
- -e POSTGRES_PASSWORD=dev \
- postgres:16
-"""
-db-url = "wt config state vars set db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'"
+post-start = [
+ """
+ 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 }}'
+ """,
+ { db = """
+ docker run -d --rm \
+ --name {{ vars.container }} \
+ -p {{ vars.port }}:5432 \
+ -e POSTGRES_DB={{ branch | sanitize_db }} \
+ -e POSTGRES_PASSWORD=dev \
+ postgres:16
+ """},
+]
[pre-remove]
-db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
+db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"
```
-The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide. The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix to avoid collisions and SQL reserved words).
+The first pipeline step derives values from the branch and stores them as vars. The second step references `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. `post-remove` reads the same vars to stop the container.
+
+The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide. The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix).
-The connection string is now accessible anywhere — not just in hooks:
+The connection string is accessible anywhere — not just in hooks:
{{ terminal(cmd="DATABASE_URL=$(wt config state vars get db-url) npm start") }}
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 056ca7216..980983e9e 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -331,27 +331,33 @@ server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ bran
## Databases
-Each worktree can have its own database. Docker containers get unique names and ports, and the connection string is stored in `vars` for use outside hooks:
+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]
-db = """
-docker run -d --rm \
- --name {{ repo }}-{{ branch | sanitize }}-postgres \
- -p {{ ('db-' ~ branch) | hash_port }}:5432 \
- -e POSTGRES_DB={{ branch | sanitize_db }} \
- -e POSTGRES_PASSWORD=dev \
- postgres:16
-"""
-db-url = "wt config state vars set db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'"
+post-start = [
+ """
+ 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 }}'
+ """,
+ { 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 {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
+db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"
```
-The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.
+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 now accessible anywhere — not just in hooks:
+The connection string is accessible anywhere — not just in hooks:
```bash
$ DATABASE_URL=$(wt config state vars get db-url) npm start
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index 9b94d2b0c..e6b1e0e12 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -58,27 +58,35 @@ Ports are deterministic — `fix-auth` always gets port 16460, regardless of whi
## Database per worktree
-Each worktree can have its own isolated database. Docker containers get unique names and ports, and the connection string is stored in `vars` for use outside hooks:
+Each worktree can have its own isolated database. A pipeline sets up names and ports as vars, then later steps and hooks reference them:
```toml
-[post-start]
-db = """
-docker run -d --rm \
- --name {{ repo }}-{{ branch | sanitize }}-postgres \
- -p {{ ('db-' ~ branch) | hash_port }}:5432 \
- -e POSTGRES_DB={{ branch | sanitize_db }} \
- -e POSTGRES_PASSWORD=dev \
- postgres:16
-"""
-db-url = "wt config state vars set db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'"
+post-start = [
+ """
+ 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 }}'
+ """,
+ { db = """
+ docker run -d --rm \
+ --name {{ vars.container }} \
+ -p {{ vars.port }}:5432 \
+ -e POSTGRES_DB={{ branch | sanitize_db }} \
+ -e POSTGRES_PASSWORD=dev \
+ postgres:16
+ """},
+]
[pre-remove]
-db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
+db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"
```
-The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide. The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix to avoid collisions and SQL reserved words).
+The first pipeline step derives values from the branch and stores them as vars. The second step references `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. `post-remove` reads the same vars to stop the container.
+
+The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide. The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix).
-The connection string is now accessible anywhere — not just in hooks:
+The connection string is accessible anywhere — not just in hooks:
```bash
$ DATABASE_URL=$(wt config state vars get db-url) npm start
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index c8ead811b..5f7ec20e5 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1444,27 +1444,33 @@ server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ bran
## Databases
-Each worktree can have its own database. Docker containers get unique names and ports, and the connection string is stored in `vars` for use outside hooks:
+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]
-db = """
-docker run -d --rm \
- --name {{ repo }}-{{ branch | sanitize }}-postgres \
- -p {{ ('db-' ~ branch) | hash_port }}:5432 \
- -e POSTGRES_DB={{ branch | sanitize_db }} \
- -e POSTGRES_PASSWORD=dev \
- postgres:16
-"""
-db-url = "wt config state vars set db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'"
+post-start = [
+ """
+ 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 }}'
+ """,
+ { 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 {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
+db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"
```
-The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.
+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 now accessible anywhere — not just in hooks:
+The connection string is accessible anywhere — not just in hooks:
```console
$ DATABASE_URL=$(wt config state vars get db-url) npm start
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 39f965f0d..6a39831b4 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -393,6 +393,10 @@ Note: This command is experimental and may change in future versions.
/// Template expression to evaluate
template: String,
+ /// Shell-escape substituted values (used internally by pipeline lazy expansion)
+ #[arg(long, hide = true)]
+ shell_escape: bool,
+
/// Show template variables and expanded result
#[arg(long)]
dry_run: bool,
diff --git a/src/commands/command_executor.rs b/src/commands/command_executor.rs
index ccb76b319..dcfa65c14 100644
--- a/src/commands/command_executor.rs
+++ b/src/commands/command_executor.rs
@@ -2,7 +2,9 @@ use anyhow::Result;
use std::collections::HashMap;
use std::path::Path;
use worktrunk::HookType;
-use worktrunk::config::{Command, CommandConfig, HookStep, UserConfig, expand_template};
+use worktrunk::config::{
+ Command, CommandConfig, HookStep, UserConfig, expand_template, template_references_var,
+};
use worktrunk::git::Repository;
use worktrunk::path::to_posix_path;
@@ -13,6 +15,9 @@ pub struct PreparedCommand {
pub name: Option<String>,
pub expanded: String,
pub context_json: String,
+ /// Raw template for lazy expansion at execution time (when template references `vars.`).
+ /// When `Some`, the `expanded` field is a placeholder — use `lazy_template` instead.
+ pub lazy_template: Option<String>,
}
/// A step in a prepared pipeline, mirroring `HookStep`.
@@ -160,17 +165,19 @@ pub fn build_hook_context(
Ok(map)
}
-/// Expand commands from a CommandConfig without approval
+/// Expand commands from a CommandConfig without approval.
///
-/// This is the canonical command expansion implementation.
-/// Returns cloned commands with their expanded forms filled in, each with per-command JSON context.
+/// When `lazy_enabled` is true, commands referencing `vars.` are validated but not
+/// expanded — they carry a `lazy_template` for deferred expansion at execution time.
+/// Only enable for pipeline steps where ordering guarantees vars are set by prior steps.
fn expand_commands(
commands: &[Command],
ctx: &CommandContext<'_>,
extra_vars: &[(&str, &str)],
hook_type: HookType,
source: HookSource,
-) -> anyhow::Result<Vec<(Command, String)>> {
+ lazy_enabled: bool,
+) -> anyhow::Result<Vec<(Command, String, Option<String>)>> {
if commands.is_empty() {
return Ok(Vec::new());
}
@@ -189,16 +196,32 @@ fn expand_commands(
cmd_context.insert("hook_name".into(), name.clone());
}
- let vars: HashMap<&str, &str> = cmd_context
- .iter()
- .map(|(k, v)| (k.as_str(), v.as_str()))
- .collect();
-
let template_name = match &cmd.name {
Some(name) => format!("{}:{}", source, name),
None => format!("{} {} hook", source, hook_type),
};
- let expanded_str = expand_template(&cmd.template, &vars, true, ctx.repo, &template_name)?;
+
+ let lazy = lazy_enabled && template_references_var(&cmd.template, "vars");
+
+ let (expanded_str, lazy_template) = if lazy {
+ // Parse-only validation: catch syntax errors upfront without rendering.
+ // Full rendering (validate_template) would fail on {{ vars.X }} because
+ // vars aren't set yet — that's the whole point of lazy expansion.
+ let env = minijinja::Environment::new();
+ env.template_from_named_str(&template_name, &cmd.template)
+ .map_err(|e| anyhow::anyhow!("syntax error in {template_name}: {e}"))?;
+ let tpl = cmd.template.clone();
+ (tpl.clone(), Some(tpl))
+ } else {
+ let vars: HashMap<&str, &str> = cmd_context
+ .iter()
+ .map(|(k, v)| (k.as_str(), v.as_str()))
+ .collect();
+ (
+ expand_template(&cmd.template, &vars, true, ctx.repo, &template_name)?,
+ None,
+ )
+ };
let context_json = serde_json::to_string(&cmd_context)
.expect("HashMap<String, String> serialization should never fail");
@@ -206,6 +229,7 @@ fn expand_commands(
result.push((
Command::with_expansion(cmd.name.clone(), cmd.template.clone(), expanded_str),
context_json,
+ lazy_template,
));
}
@@ -232,14 +256,18 @@ pub fn prepare_commands(
return Ok(Vec::new());
}
- let expanded_with_json = expand_commands(&commands, ctx, extra_vars, hook_type, source)?;
+ // Lazy expansion for pipeline configs (sequential ordering guarantees vars are
+ // set by prior steps). Flat configs (concurrent table) expand eagerly.
+ let lazy = command_config.is_pipeline();
+ let expanded_with_json = expand_commands(&commands, ctx, extra_vars, hook_type, source, lazy)?;
Ok(expanded_with_json
.into_iter()
- .map(|(cmd, context_json)| PreparedCommand {
+ .map(|(cmd, context_json, lazy_template)| PreparedCommand {
name: cmd.name,
expanded: cmd.expanded,
context_json,
+ lazy_template,
})
.collect())
}
@@ -272,7 +300,7 @@ pub fn prepare_steps(
.collect();
let all_commands: Vec<Command> = command_config.commands().cloned().collect();
- let all_expanded = expand_commands(&all_commands, ctx, extra_vars, hook_type, source)?;
+ let all_expanded = expand_commands(&all_commands, ctx, extra_vars, hook_type, source, true)?;
let mut expanded_iter = all_expanded.into_iter();
let mut result = Vec::new();
@@ -280,20 +308,22 @@ pub fn prepare_steps(
let chunk: Vec<_> = expanded_iter.by_ref().take(size).collect();
match step {
HookStep::Single(_) => {
- let (cmd, json) = chunk.into_iter().next().unwrap();
+ let (cmd, json, lazy) = chunk.into_iter().next().unwrap();
result.push(PreparedStep::Single(PreparedCommand {
name: cmd.name,
expanded: cmd.expanded,
context_json: json,
+ lazy_template: lazy,
}));
}
HookStep::Concurrent(_) => {
let prepared = chunk
.into_iter()
- .map(|(cmd, json)| PreparedCommand {
+ .map(|(cmd, json, lazy)| PreparedCommand {
name: cmd.name,
expanded: cmd.expanded,
context_json: json,
+ lazy_template: lazy,
})
.collect();
result.push(PreparedStep::Concurrent(prepared));
@@ -303,3 +333,30 @@ pub fn prepare_steps(
Ok(result)
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_template_references_var_for_vars() {
+ // Real vars references
+ assert!(template_references_var("{{ vars.container }}", "vars"));
+ assert!(template_references_var("{{vars.container}}", "vars"));
+ assert!(template_references_var(
+ "docker run --name {{ vars.name }}",
+ "vars"
+ ));
+ assert!(template_references_var(
+ "{% if vars.key %}yes{% endif %}",
+ "vars"
+ ));
+
+ // Literal text — not a template reference
+ assert!(!template_references_var(
+ "echo hello > template_vars.txt",
+ "vars"
+ ));
+ assert!(!template_references_var("no vars references here", "vars"));
+ }
+}
diff --git a/src/commands/eval.rs b/src/commands/eval.rs
index 6908926bb..2ad4bb7ba 100644
--- a/src/commands/eval.rs
+++ b/src/commands/eval.rs
@@ -1,8 +1,8 @@
//! Eval command implementation
//!
//! Evaluates a template expression in the current worktree context and prints
-//! the result to stdout. Designed for scripting — output is raw (no shell
-//! escaping, no decoration).
+//! the result to stdout. Output is raw by default; `--shell-escape` enables
+//! shell escaping for safe use with `eval`.
use std::collections::HashMap;
@@ -18,7 +18,7 @@ use crate::commands::command_executor::{CommandContext, build_hook_context};
///
/// With `dry_run`, prints the template variables and the expanded result
/// to stderr — useful for debugging templates.
-pub fn step_eval(template: &str, dry_run: bool) -> anyhow::Result<()> {
+pub fn step_eval(template: &str, shell_escape: bool, dry_run: bool) -> anyhow::Result<()> {
let repo = Repository::current()?;
let config = UserConfig::load()?;
@@ -34,8 +34,7 @@ pub fn step_eval(template: &str, dry_run: bool) -> anyhow::Result<()> {
.map(|(k, v)| (k.as_str(), v.as_str()))
.collect();
- // No shell escaping — output is literal for scripting
- let result = expand_template(template, &vars, false, &repo, "eval")?;
+ let result = expand_template(template, &vars, shell_escape, &repo, "eval")?;
if dry_run {
let mut keys: Vec<&str> = context_map.keys().map(|k| k.as_str()).collect();
diff --git a/src/commands/hooks.rs b/src/commands/hooks.rs
index 47eb21a95..daac79a9b 100644
--- a/src/commands/hooks.rs
+++ b/src/commands/hooks.rs
@@ -244,6 +244,7 @@ pub fn spawn_background_hooks(
ctx.branch_or_head(),
&hook_log,
Some(&cmd.prepared.context_json),
+ &[],
) {
let err_msg = err.to_string();
let message = match &cmd.prepared.name {
@@ -276,33 +277,58 @@ pub struct SourcedStep {
pub display_path: Option<PathBuf>,
}
-/// Build a compound shell command from pipeline steps.
+/// Build a compound shell command from pipeline steps, collecting env vars for
+/// lazy template expansion.
///
/// Serial steps are chained with `&&`. Concurrent groups use background
-/// processes with `wait`. The entire result is one shell command string
-/// suitable for `spawn_detached`.
+/// processes with `wait`. Commands referencing `vars.` are wrapped in
+/// `eval "$(wt step eval --shell-escape ...)"` and their raw templates are
+/// returned as env vars for the spawned process.
///
-/// Example output: `cmd1 && cmd2 && { cmd3 & cmd4 & wait; }`
-fn build_pipeline_command(steps: &[SourcedStep]) -> String {
+/// Returns `(shell_command, env_vars)`.
+fn build_pipeline_command(steps: &[SourcedStep]) -> (String, Vec<(String, String)>) {
+ let wt_bin = std::env::current_exe()
+ .ok()
+ .map(|p| shell_escape::escape(p.to_string_lossy()).into_owned())
+ .unwrap_or_else(|| "wt".to_string());
+
let mut parts = Vec::new();
+ let mut env_vars: Vec<(String, String)> = Vec::new();
+
for step in steps {
match &step.step {
PreparedStep::Single(cmd) => {
// Wrap in braces to prevent operator interaction between steps.
// Without this, `false || echo fallback && echo next` would
// parse as `false || (echo fallback && echo next)`.
- parts.push(format!("{{ {}; }}", cmd.expanded));
+ parts.push(format!(
+ "{{ {}; }}",
+ format_cmd(cmd, &wt_bin, &mut env_vars)
+ ));
}
PreparedStep::Concurrent(cmds) => {
let bg: Vec<String> = cmds
.iter()
- .map(|c| format!("{{ {}; }} &", c.expanded))
+ .map(|c| format!("{{ {}; }} &", format_cmd(c, &wt_bin, &mut env_vars)))
.collect();
parts.push(format!("{{ {} wait; }}", bg.join(" ")));
}
}
}
- parts.join(" && ")
+ (parts.join(" && "), env_vars)
+}
+
+/// Format a single command for the pipeline, using lazy eval wrapping for commands
+/// with `lazy_template`.
+fn format_cmd(cmd: &PreparedCommand, wt_bin: &str, env_vars: &mut Vec<(String, String)>) -> String {
+ match &cmd.lazy_template {
+ Some(template) => {
+ let var_name = format!("__WT_TPL_{}", env_vars.len());
+ env_vars.push((var_name.clone(), template.clone()));
+ format!(r#"eval "$({wt_bin} step eval --shell-escape "${var_name}")"#)
+ }
+ None => cmd.expanded.clone(),
+ }
}
/// Format a summary description of a pipeline for display.
@@ -371,7 +397,7 @@ pub fn spawn_hook_pipeline(ctx: &CommandContext, steps: Vec<SourcedStep>) -> any
};
eprintln!("{}", progress_message(message));
- let pipeline_cmd = build_pipeline_command(&steps);
+ let (pipeline_cmd, lazy_env) = build_pipeline_command(&steps);
let hook_log = HookLog::hook(source, hook_type, "pipeline");
let log_label = format!("{hook_type} {source} pipeline");
@@ -382,6 +408,11 @@ pub fn spawn_hook_pipeline(ctx: &CommandContext, steps: Vec<SourcedStep>) -> any
PreparedStep::Concurrent(cmds) => cmds.first().map(|c| c.context_json.as_str()),
});
+ let extra_env: Vec<(&str, &str)> = lazy_env
+ .iter()
+ .map(|(k, v)| (k.as_str(), v.as_str()))
+ .collect();
+
if let Err(err) = spawn_detached(
ctx.repo,
ctx.worktree_path,
@@ -389,6 +420,7 @@ pub fn spawn_hook_pipeline(ctx: &CommandContext, steps: Vec<SourcedStep>) -> any
ctx.branch_or_head(),
&hook_log,
context_json,
+ &extra_env,
) {
eprintln!(
"{}",
@@ -525,10 +557,26 @@ pub fn run_hook_with_filter(
for cmd in commands {
cmd.announce()?;
+ // Lazy commands (referencing vars.) are expanded just before execution
+ // so that vars set by earlier commands in the pipeline are available.
+ let expanded = if let Some(ref template) = cmd.prepared.lazy_template {
+ let context_map: std::collections::HashMap<String, String> =
+ serde_json::from_str(&cmd.prepared.context_json)
+ .expect("context_json round-trip should never fail");
+ let vars: std::collections::HashMap<&str, &str> = context_map
+ .iter()
+ .map(|(k, v)| (k.as_str(), v.as_str()))
+ .collect();
+ let name = cmd.summary_name();
+ worktrunk::config::expand_template(template, &vars, true, ctx.repo, &name)?
+ } else {
+ cmd.prepared.expanded.clone()
+ };
+
let log_label = format!("{} {}", cmd.hook_type, cmd.summary_name());
if let Err(err) = execute_command_in_worktree(
ctx.worktree_path,
- &cmd.prepared.expanded,
+ &expanded,
Some(&cmd.prepared.context_json),
Some(&log_label),
) {
@@ -745,6 +793,7 @@ mod tests {
name: name.map(String::from),
expanded: expanded.to_string(),
context_json: "{}".to_string(),
+ lazy_template: None,
}
}
@@ -757,8 +806,9 @@ mod tests {
"npm run build",
))),
];
- let cmd = build_pipeline_command(&steps);
+ let (cmd, env) = build_pipeline_command(&steps);
assert_eq!(cmd, "{ npm install; } && { npm run build; }");
+ assert!(env.is_empty());
}
#[test]
@@ -770,11 +820,12 @@ mod tests {
make_cmd(Some("lint"), "npm run lint"),
])),
];
- let cmd = build_pipeline_command(&steps);
+ let (cmd, env) = build_pipeline_command(&steps);
assert_eq!(
cmd,
"{ npm install; } && { { npm run build; } & { npm run lint; } & wait; }"
);
+ assert!(env.is_empty());
}
#[test]
@@ -783,8 +834,9 @@ mod tests {
Some("only"),
"echo hi",
)]))];
- let cmd = build_pipeline_command(&steps);
+ let (cmd, env) = build_pipeline_command(&steps);
assert_eq!(cmd, "{ { echo hi; } & wait; }");
+ assert!(env.is_empty());
}
#[test]
@@ -825,4 +877,88 @@ mod tests {
let single = CommandConfig::single("npm install");
assert!(!single.is_pipeline());
}
+
+ fn make_lazy_cmd(name: Option<&str>, template: &str) -> PreparedCommand {
+ PreparedCommand {
+ name: name.map(String::from),
+ expanded: template.to_string(),
+ context_json: "{}".to_string(),
+ lazy_template: Some(template.to_string()),
+ }
+ }
+
+ #[test]
+ fn test_build_pipeline_command_lazy_step() {
+ let steps = vec![
+ make_sourced_step(PreparedStep::Single(make_cmd(None, "echo setup"))),
+ make_sourced_step(PreparedStep::Single(make_lazy_cmd(
+ Some("db"),
+ "docker run --name {{ vars.container }}",
+ ))),
+ ];
+ let (cmd, env) = build_pipeline_command(&steps);
+
+ // Lazy step uses eval wrapping with env var reference
+ assert!(
+ cmd.contains("eval \"$("),
+ "should contain eval wrapping: {cmd}"
+ );
+ assert!(
+ cmd.contains("step eval --shell-escape"),
+ "should reference step eval: {cmd}"
+ );
+ assert!(
+ cmd.contains("$__WT_TPL_0"),
+ "should reference env var: {cmd}"
+ );
+
+ // Env var contains the raw template
+ assert_eq!(env.len(), 1);
+ assert_eq!(env[0].0, "__WT_TPL_0");
+ assert_eq!(env[0].1, "docker run --name {{ vars.container }}");
+ }
+
+ #[test]
+ fn test_build_pipeline_command_mixed_lazy_and_eager() {
+ let steps = vec![
+ make_sourced_step(PreparedStep::Single(make_cmd(None, "echo setup"))),
+ make_sourced_step(PreparedStep::Concurrent(vec![
+ make_lazy_cmd(Some("db"), "docker run {{ vars.name }}"),
+ make_cmd(Some("lint"), "npm run lint"),
+ ])),
+ ];
+ let (cmd, env) = build_pipeline_command(&steps);
+
+ // First step is eager (no eval wrapping)
+ assert!(cmd.starts_with("{ echo setup; }"), "eager step: {cmd}");
+
+ // Concurrent group has one lazy and one eager
+ assert!(cmd.contains("npm run lint"), "eager concurrent cmd: {cmd}");
+ assert!(cmd.contains("$__WT_TPL_0"), "lazy concurrent cmd: {cmd}");
+
+ // Only one env var (for the lazy command)
+ assert_eq!(env.len(), 1);
+ assert_eq!(env[0].1, "docker run {{ vars.name }}");
+ }
+
+ #[test]
+ fn test_build_pipeline_command_multiple_lazy_steps() {
+ let steps = vec![
+ make_sourced_step(PreparedStep::Single(make_cmd(None, "echo setup"))),
+ make_sourced_step(PreparedStep::Single(make_lazy_cmd(
+ None,
+ "echo {{ vars.a }}",
+ ))),
+ make_sourced_step(PreparedStep::Single(make_lazy_cmd(
+ None,
+ "echo {{ vars.b }}",
+ ))),
+ ];
+ let (_, env) = build_pipeline_command(&steps);
+
+ // Each lazy step gets its own numbered env var
+ assert_eq!(env.len(), 2);
+ assert_eq!(env[0].0, "__WT_TPL_0");
+ assert_eq!(env[1].0, "__WT_TPL_1");
+ }
}
diff --git a/src/commands/process.rs b/src/commands/process.rs
index 7e82bdff8..fd4106cc6 100644
--- a/src/commands/process.rs
+++ b/src/commands/process.rs
@@ -194,6 +194,7 @@ fn posix_command_separator(command: &str) -> &'static str {
/// * `branch` - Branch name for log organization
/// * `hook_log` - Log specification (determines the log filename)
/// * `context_json` - Optional JSON context to pipe to command's stdin
+/// * `extra_env` - Additional environment variables for the spawned process
///
/// # Returns
/// Path to the log file where output is being written
@@ -204,6 +205,7 @@ pub fn spawn_detached(
branch: &str,
hook_log: &HookLog,
context_json: Option<&str>,
+ extra_env: &[(&str, &str)],
) -> anyhow::Result<std::path::PathBuf> {
// Create log directory in the common git directory
let log_dir = repo.wt_logs_dir();
@@ -233,12 +235,12 @@ pub fn spawn_detached(
#[cfg(unix)]
{
- spawn_detached_unix(worktree_path, command, log_file, context_json)?;
+ spawn_detached_unix(worktree_path, command, log_file, context_json, extra_env)?;
}
#[cfg(windows)]
{
- spawn_detached_windows(worktree_path, command, log_file, context_json)?;
+ spawn_detached_windows(worktree_path, command, log_file, context_json, extra_env)?;
}
Ok(log_path)
@@ -250,6 +252,7 @@ fn spawn_detached_unix(
command: &str,
log_file: fs::File,
context_json: Option<&str>,
+ extra_env: &[(&str, &str)],
) -> anyhow::Result<()> {
use std::os::unix::process::CommandExt;
@@ -287,6 +290,7 @@ fn spawn_detached_unix(
.stderr(Stdio::from(log_file))
// Prevent hooks from writing to the directive file
.env_remove(worktrunk::shell_exec::DIRECTIVE_FILE_ENV_VAR)
+ .envs(extra_env.iter().map(|(k, v)| (k, v)))
.process_group(0) // New process group, not in PTY's foreground group
.spawn()
.context("Failed to spawn detached process")?;
@@ -305,6 +309,7 @@ fn spawn_detached_windows(
command: &str,
log_file: fs::File,
context_json: Option<&str>,
+ extra_env: &[(&str, &str)],
) -> anyhow::Result<()> {
use std::os::windows::process::CommandExt;
use worktrunk::shell_exec::ShellConfig;
@@ -360,6 +365,7 @@ fn spawn_detached_windows(
.stderr(Stdio::from(log_file))
// Prevent hooks from writing to the directive file
.env_remove(worktrunk::shell_exec::DIRECTIVE_FILE_ENV_VAR)
+ .envs(extra_env.iter().map(|(k, v)| (k, v)))
.creation_flags(CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS)
.spawn()
.context("Failed to spawn detached process")?;
diff --git a/src/commands/worktree/resolve.rs b/src/commands/worktree/resolve.rs
index 23993fa41..d2d66b343 100644
--- a/src/commands/worktree/resolve.rs
+++ b/src/commands/worktree/resolve.rs
@@ -334,12 +334,8 @@ const BARE_REPO_WORKTREE_PATH: &str = "{{ repo_path }}/../{{ branch | sanitize }
/// Check whether a template string references `{{ repo }}` or `{{ main_worktree }}`.
fn template_references_repo_name(template: &str) -> bool {
- let env = minijinja::Environment::new();
- let Ok(tmpl) = env.template_from_str(template) else {
- return false;
- };
- let vars = tmpl.undeclared_variables(false);
- vars.contains("repo") || vars.contains("main_worktree")
+ worktrunk::config::template_references_var(template, "repo")
+ || worktrunk::config::template_references_var(template, "main_worktree")
}
/// Offer to set a project-level `worktree-path` for bare repos with hidden directory names.
diff --git a/src/config/expansion.rs b/src/config/expansion.rs
index 41291ceb5..2228d2a23 100644
--- a/src/config/expansion.rs
+++ b/src/config/expansion.rs
@@ -350,6 +350,19 @@ fn setup_template_env(repo: &Repository) -> Environment<'static> {
/// would be fragile and context-dependent.
///
/// No verbose logging is performed — this is a pre-flight check, not the real expansion.
+///
+/// Check if a template references a specific top-level variable.
+///
+/// Uses minijinja's AST analysis rather than string matching, avoiding false
+/// positives from literal text like `template_vars.txt`.
+pub fn template_references_var(template: &str, var: &str) -> bool {
+ let env = minijinja::Environment::new();
+ let Ok(tmpl) = env.template_from_str(template) else {
+ return false;
+ };
+ tmpl.undeclared_variables(false).contains(var)
+}
+
pub fn validate_template(
template: &str,
repo: &Repository,
diff --git a/src/config/mod.rs b/src/config/mod.rs
index a9b6ac6c0..6dcb27283 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -86,7 +86,8 @@ pub use deprecation::write_migration_file;
pub use deprecation::{DEPRECATED_SECTION_KEYS, key_belongs_in, warn_unknown_fields};
pub use expansion::{
DEPRECATED_TEMPLATE_VARS, TEMPLATE_VARS, TemplateExpandError, expand_template,
- redact_credentials, sanitize_branch_name, sanitize_db, short_hash, validate_template,
+ redact_credentials, sanitize_branch_name, sanitize_db, short_hash, template_references_var,
+ validate_template,
};
pub use hooks::HooksConfig;
pub use project::{
diff --git a/src/main.rs b/src/main.rs
index 9725a5cb9..1533d216f 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -321,7 +321,11 @@ fn handle_step_command(action: StepCommand) -> anyhow::Result<()> {
dry_run,
force,
} => step_copy_ignored(from.as_deref(), to.as_deref(), dry_run, force),
- StepCommand::Eval { template, dry_run } => step_eval(&template, dry_run),
+ StepCommand::Eval {
+ template,
+ shell_escape,
+ dry_run,
+ } => step_eval(&template, shell_escape, dry_run),
StepCommand::ForEach { args } => step_for_each(args),
StepCommand::Promote { branch } => {
handle_promote(branch.as_deref()).map(|result| match result {
diff --git a/src/output/handlers.rs b/src/output/handlers.rs
index 6f31f9e09..60f244259 100644
--- a/src/output/handlers.rs
+++ b/src/output/handlers.rs
@@ -72,6 +72,7 @@ fn spawn_background_removal(
log_label,
&HookLog::internal(InternalOp::Remove),
None,
+ &[],
)?;
Ok(())
}
diff --git a/tests/integration_tests/eval.rs b/tests/integration_tests/eval.rs
index 37c131732..191329a28 100644
--- a/tests/integration_tests/eval.rs
+++ b/tests/integration_tests/eval.rs
@@ -79,3 +79,30 @@ fn test_eval_conditional(repo: TestRepo) {
None,
));
}
+
+#[rstest]
+fn test_eval_shell_escape(repo: TestRepo) {
+ // --shell-escape quotes values containing shell metacharacters
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["eval", "--shell-escape", "echo {{ branch }}"],
+ None,
+ ));
+}
+
+#[rstest]
+fn test_eval_shell_escape_with_vars(repo: TestRepo) {
+ // Set a var with spaces, then expand with shell escaping
+ repo.run_git(&["config", "worktrunk.state.main.vars.name", "my container"]);
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &[
+ "eval",
+ "--shell-escape",
+ "docker run --name {{ vars.name }}"
+ ],
+ None,
+ ));
+}
diff --git a/tests/integration_tests/user_hooks.rs b/tests/integration_tests/user_hooks.rs
index b84259d9d..a6452c385 100644
--- a/tests/integration_tests/user_hooks.rs
+++ b/tests/integration_tests/user_hooks.rs
@@ -2364,3 +2364,46 @@ fn test_user_post_start_pipeline_failure_skips_later_steps(repo: TestRepo) {
"Later pipeline steps should NOT run after serial step failure"
);
}
+
+#[rstest]
+fn test_user_post_start_pipeline_lazy_vars_foreground(repo: TestRepo) {
+ // Pipeline step 1 sets a var, step 2 uses it via {{ vars.name }}.
+ // Foreground mode exercises the in-process lazy re-expansion path
+ // in run_hook_with_filter.
+ repo.write_test_config(
+ r#"post-start = [
+ "git config worktrunk.state.main.vars.name '{{ branch | sanitize }}-postgres'",
+ { db = "echo {{ vars.name }} > lazy_expanded.txt" }
+]
+"#,
+ );
+
+ // Run the hook in foreground on the main worktree.
+ // Step 1 uses `git config` directly (avoids needing `wt` on PATH in CI).
+ let mut cmd = crate::common::wt_command();
+ cmd.current_dir(repo.root_path());
+ cmd.env("WORKTRUNK_CONFIG_PATH", repo.test_config_path());
+ cmd.args(["hook", "post-start", "--yes", "--foreground"]);
+
+ let output = cmd.output().expect("Failed to run foreground hook");
+
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(
+ output.status.success(),
+ "Foreground hook should succeed.\nstdout: {}\nstderr: {stderr}",
+ String::from_utf8_lossy(&output.stdout),
+ );
+
+ // With foreground, marker file should exist immediately
+ let marker_file = repo.root_path().join("lazy_expanded.txt");
+ assert!(
+ marker_file.exists(),
+ "Foreground lazy expansion should create marker file"
+ );
+
+ let content = fs::read_to_string(&marker_file).unwrap().trim().to_string();
+ assert_eq!(
+ content, "main-postgres",
+ "Lazy step should see var set by prior step"
+ );
+}
diff --git a/tests/snapshots/integration__integration_tests__eval__eval_shell_escape.snap b/tests/snapshots/integration__integration_tests__eval__eval_shell_escape.snap
new file mode 100644
index 000000000..b05c1f54d
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__eval__eval_shell_escape.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/eval.rs
+info:
+ program: wt
+ args:
+ - step
+ - eval
+ - "--shell-escape"
+ - "echo {{ branch }}"
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+echo main
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__eval__eval_shell_escape_with_vars.snap b/tests/snapshots/integration__integration_tests__eval__eval_shell_escape_with_vars.snap
new file mode 100644
index 000000000..c35c62195
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__eval__eval_shell_escape_with_vars.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/eval.rs
+info:
+ program: wt
+ args:
+ - step
+ - eval
+ - "--shell-escape"
+ - "docker run --name {{ vars.name }}"
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+docker run --name 'my container'
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__switch__switch_create_with_progress.snap b/tests/snapshots/integration__integration_tests__switch__switch_create_with_progress.snap
index adfdc0d10..8a5e5986e 100644
--- a/tests/snapshots/integration__integration_tests__switch__switch_create_with_progress.snap
+++ b/tests/snapshots/integration__integration_tests__switch__switch_create_with_progress.snap
@@ -1,5 +1,6 @@
---
source: tests/integration_tests/switch.rs
+assertion_line: 74
info:
program: wt
args: