Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
refactor(eval): inspect template variables via -v, not --dry-run (#3078)
Maximilian Roosa01a9020caf5
diff --git a/docs/content/step.md b/docs/content/step.mdindex b27090284..bbd00ea7e 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -534,13 +534,17 @@ Use conditionals and filters:feature_auth_oauth2_a1b{% end %}-Show available template variables:--{% terminal(cmd="wt step eval --dry-run '__WT_OPEN__ branch __WT_CLOSE__'") %}-branch=feature/auth-oauth2-worktree_path=/home/user/projects/myapp-feature-auth-oauth2-----Result: feature/auth-oauth2+List the available template variables with `-v` (alongside the expansion, on stderr):++{% terminal(cmd="wt step eval -v '__WT_OPEN__ branch __WT_CLOSE__'") %}+○ Available template variables+ branch = feature/auth-oauth2+ worktree_path = /home/user/projects/myapp-feature-auth-oauth2+○ Expanding eval+ {{ branch }}+ →+ feature/auth-oauth2+feature/auth-oauth2{% end %}Note: This command is experimental and may change in future versions.@@ -559,9 +563,6 @@ Usage: <b><span class=c>wt step eval</span></b> <span class=c>[OPTIONS]</span> <Template expression to evaluate<b><span class=g>Options:</span></b>- <b><span class=c>--dry-run</span></b>- Show template variables and expanded result-<b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>Print help (see a summary with '-h')diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex 1db454609..965adf0c1 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -550,14 +550,18 @@ $ wt step eval '{{ branch | sanitize_db }}'feature_auth_oauth2_a1b```-Show available template variables:+List the available template variables with `-v` (alongside the expansion, on stderr):```bash-$ wt step eval --dry-run '{{ branch }}'-branch=feature/auth-oauth2-worktree_path=/home/user/projects/myapp-feature-auth-oauth2-----Result: feature/auth-oauth2+$ wt step eval -v '{{ branch }}'+○ Available template variables+ branch = feature/auth-oauth2+ worktree_path = /home/user/projects/myapp-feature-auth-oauth2+○ Expanding eval+ {{ branch }}+ →+ feature/auth-oauth2+feature/auth-oauth2```Note: This command is experimental and may change in future versions.@@ -576,9 +580,6 @@ Arguments:Template expression to evaluateOptions:- --dry-run- Show template variables and expanded result--h, --helpPrint help (see a summary with '-h')diff --git a/src/cli/step.rs b/src/cli/step.rsindex d937c5fdc..ce8c06009 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -431,14 +431,18 @@ $ wt step eval '{{ branch | sanitize_db }}'feature_auth_oauth2_a1b```-Show available template variables:+List the available template variables with `-v` (alongside the expansion, on stderr):```console-$ wt step eval --dry-run '{{ branch }}'-branch=feature/auth-oauth2-worktree_path=/home/user/projects/myapp-feature-auth-oauth2-----Result: feature/auth-oauth2+$ wt step eval -v '{{ branch }}'+○ Available template variables+ branch = feature/auth-oauth2+ worktree_path = /home/user/projects/myapp-feature-auth-oauth2+○ Expanding eval+ {{ branch }}+ →+ feature/auth-oauth2+feature/auth-oauth2```Note: This command is experimental and may change in future versions.@@ -447,10 +451,6 @@ Note: This command is experimental and may change in future versions.Eval {/// Template expression to evaluatetemplate: String,-- /// Show template variables and expanded result- #[arg(long)]- dry_run: bool,},/// \[experimental\] Run command in each worktreediff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.mdindex f963c0bee..330123688 100644--- a/src/commands/CLAUDE.md+++ b/src/commands/CLAUDE.md@@ -116,6 +116,14 @@ Keep the first line of flag and argument descriptions brief—aim for 3-6 words.The help text should be scannable. Users reading `wt switch --help` need to quickly understand what each flag does without parsing long sentences.+## `--dry-run` and `-v`++`--dry-run` previews the mutation a command would perform without performing it. A command that changes nothing has nothing to preview, so it carries no `--dry-run`; its inspection output belongs to `-v` instead. `wt step eval` expands a template and prints the result, so it lists the available variables under `-v`, not behind a `--dry-run`.++The flags answer different questions: `--dry-run` is "what would this change?", `-v` is "what is this doing?" (template variables, expansion, echoed `$ git …` subprocesses).++Both render in the gutter house style: `format_heading` for sections, `format_with_gutter` / `format_bash_with_gutter` for quoted blocks, `info_message` / `hint_message` for status lines. The `/writing-user-outputs` skill covers the helpers, the stdout/stderr split, and when to page.+## CLI Help Text PlacementHelp text has three levels:diff --git a/src/commands/eval.rs b/src/commands/eval.rsindex 1ceaafc08..6006238f6 100644--- a/src/commands/eval.rs+++ b/src/commands/eval.rs@@ -5,9 +5,11 @@use std::collections::HashMap;+use color_print::cformat;use worktrunk::config::{UserConfig, expand_template};use worktrunk::git::Repository;use worktrunk::shell_exec::ShellEscapeMode;+use worktrunk::styling::{eprintln, format_with_gutter, info_message, println, verbosity};use crate::commands::command_executor::{CommandContext, build_hook_context};@@ -16,9 +18,11 @@ use crate::commands::command_executor::{CommandContext, build_hook_context};/// Prints the expanded result to stdout with a trailing newline. All hook/// template variables and filters are available.///-/// 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<()> {+/// `eval` mutates nothing, so it has no `--dry-run`. Variable discovery lives+/// in the verbose lane instead: `-v` lists the available template variables on+/// stderr, above the `{{ template }} → result` expansion view that+/// `expand_template` renders at `-v`.+pub fn step_eval(template: &str) -> anyhow::Result<()> {let repo = Repository::current()?;let config = UserConfig::load()?;@@ -29,23 +33,28 @@ pub fn step_eval(template: &str, dry_run: bool) -> anyhow::Result<()> {let ctx = CommandContext::new(&repo, &config, branch.as_deref(), &worktree_path, false);let context_map = build_hook_context(&ctx, &[], None)?;+ if verbosity() >= 1 {+ let width = context_map.keys().map(String::len).max().unwrap_or(0);+ let mut keys: Vec<&str> = context_map.keys().map(String::as_str).collect();+ keys.sort();+ let listing = keys+ .iter()+ .map(|key| {+ let pad = " ".repeat(width - key.len());+ cformat!("<bold>{key}</>{pad} = {}", context_map[*key])+ })+ .collect::<Vec<_>>()+ .join("\n");+ eprintln!("{}", info_message("Available template variables"));+ eprintln!("{}", format_with_gutter(&listing, None));+ }+let vars: HashMap<&str, &str> = context_map.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect();let result = expand_template(template, &vars, ShellEscapeMode::Literal, &repo, "eval")?;-- if dry_run {- let mut keys: Vec<&str> = context_map.keys().map(|k| k.as_str()).collect();- keys.sort();- for key in keys {- eprintln!("{}={}", key, context_map[key]);- }- eprintln!("---");- eprintln!("Result: {result}");- } else {- println!("{result}");- }+ println!("{result}");Ok(())}diff --git a/src/docs.rs b/src/docs.rsindex 927e6adb3..c09fd38de 100644--- a/src/docs.rs+++ b/src/docs.rs@@ -167,11 +167,12 @@ mod tests {// Multi-line output, no {{ }} → cmd parameterassert_snapshot!(convert_dollar_console_to_terminal(- "```console\n$ wt step eval --dry-run 'test'\nbranch=feature/auth\nResult: feature/auth\n```"+ "```console\n$ wt step eval -v 'test'\n○ Available template variables\n branch = feature/auth\ntest\n```"), @r#"- {% terminal(cmd="wt step eval --dry-run 'test'") %}- branch=feature/auth- Result: feature/auth+ {% terminal(cmd="wt step eval -v 'test'") %}+ ○ Available template variables+ branch = feature/auth+ test{% end %}"#);diff --git a/src/main.rs b/src/main.rsindex 6a1951527..eda8298cf 100644--- a/src/main.rs+++ b/src/main.rs@@ -363,7 +363,7 @@ fn handle_step_command(action: StepCommand, yes: bool) -> anyhow::Result<()> {force,format,} => step_copy_ignored(from.as_deref(), to.as_deref(), dry_run, force, format),- StepCommand::Eval { template, dry_run } => step_eval(&template, dry_run),+ StepCommand::Eval { template } => step_eval(&template),StepCommand::ForEach { format, args } => step_for_each(args, format),StepCommand::Promote { branch } => {handle_promote(branch.as_deref()).map(|result| match result {diff --git a/tests/integration_tests/eval.rs b/tests/integration_tests/eval.rsindex 27366fbb3..0373d7baf 100644--- a/tests/integration_tests/eval.rs+++ b/tests/integration_tests/eval.rs@@ -1,6 +1,6 @@//! Integration tests for `wt step eval`-use crate::common::{TestRepo, make_snapshot_cmd, repo};+use crate::common::{TestRepo, make_snapshot_cmd, make_snapshot_cmd_with_global_flags, repo};use insta_cmd::assert_cmd_snapshot;use rstest::rstest;@@ -58,12 +58,13 @@ fn test_eval_template_error(repo: TestRepo) {}#[rstest]-fn test_eval_dry_run(repo: TestRepo) {- assert_cmd_snapshot!(make_snapshot_cmd(+fn test_eval_verbose(repo: TestRepo) {+ assert_cmd_snapshot!(make_snapshot_cmd_with_global_flags(&repo,"step",- &["eval", "--dry-run", "{{ branch | hash_port }}"],+ &["eval", "{{ branch | hash_port }}"],None,+ &["--verbose"],));}diff --git a/tests/snapshots/integration__integration_tests__eval__eval_dry_run.snap b/tests/snapshots/integration__integration_tests__eval__eval_verbose.snapsimilarity index 54%rename from tests/snapshots/integration__integration_tests__eval__eval_dry_run.snaprename to tests/snapshots/integration__integration_tests__eval__eval_verbose.snapindex b7111cd3c..0e1d14fbe 100644--- a/tests/snapshots/integration__integration_tests__eval__eval_dry_run.snap+++ b/tests/snapshots/integration__integration_tests__eval__eval_verbose.snap@@ -3,9 +3,9 @@ source: tests/integration_tests/eval.rsinfo:program: wtargs:+ - "--verbose"- step- eval- - "--dry-run"- "{{ branch | hash_port }}"env:APPDATA: "[TEST_CONFIG_HOME]"@@ -46,24 +46,28 @@ info:success: trueexit_code: 0----- stdout -----+12107----- stderr ------branch=main-commit=05a4a45d0b981dad5c27db59dca482836d59f89e-cwd=_REPO_-default_branch=main-main_worktree=repo-main_worktree_path=_REPO_-primary_worktree_path=_REPO_-remote=origin-remote_url=../origin.git-repo=repo-repo_path=_REPO_-repo_root=_REPO_-short_commit=05a4a45-upstream=origin/main-worktree=_REPO_-worktree_name=repo-worktree_path=_REPO_-----Result: 12107+[2m○[22m Available template variables+[107m [0m [1mbranch[22m = main+[107m [0m [1mcommit[22m = 05a4a45d0b981dad5c27db59dca482836d59f89e+[107m [0m [1mcwd[22m = _REPO_+[107m [0m [1mdefault_branch[22m = main+[107m [0m [1mmain_worktree[22m = repo+[107m [0m [1mmain_worktree_path[22m = _REPO_+[107m [0m [1mprimary_worktree_path[22m = _REPO_+[107m [0m [1mremote[22m = origin+[107m [0m [1mremote_url[22m = ../origin.git+[107m [0m [1mrepo[22m = repo+[107m [0m [1mrepo_path[22m = _REPO_+[107m [0m [1mrepo_root[22m = _REPO_+[107m [0m [1mshort_commit[22m = 05a4a45+[107m [0m [1mupstream[22m = origin/main+[107m [0m [1mworktree[22m = _REPO_+[107m [0m [1mworktree_name[22m = repo+[107m [0m [1mworktree_path[22m = _REPO_+[2m○[22m Expanding [1meval[22m+[107m [0m [2m[0m[2m[32m{{[0m[2m[0m[2m branch [0m[2m[36m|[0m[2m [0m[2m[34mhash_port[0m[2m [0m[2m[32m}}[0m+[107m [0m [2m→[22m+[107m [0m [2m[0m[2m[34m12107[0m