Skip to content

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.md
index 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 &#39;-h&#39;)
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 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 evaluate
Options:
- --dry-run
- Show template variables and expanded result
-
-h, --help
Print help (see a summary with '-h')
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 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 evaluate
template: String,
-
- /// Show template variables and expanded result
- #[arg(long)]
- dry_run: bool,
},
/// \[experimental\] Run command in each worktree
diff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.md
index 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 Placement
Help text has three levels:
diff --git a/src/commands/eval.rs b/src/commands/eval.rs
index 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.rs
index 927e6adb3..c09fd38de 100644
--- a/src/docs.rs
+++ b/src/docs.rs
@@ -167,11 +167,12 @@ mod tests {
// Multi-line output, no {{ }} → cmd parameter
assert_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.rs
index 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.rs
index 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.snap
similarity index 54%
rename from tests/snapshots/integration__integration_tests__eval__eval_dry_run.snap
rename to tests/snapshots/integration__integration_tests__eval__eval_verbose.snap
index 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.rs
info:
program: wt
args:
+ - "--verbose"
- step
- eval
- - "--dry-run"
- "{{ branch | hash_port }}"
env:
APPDATA: "[TEST_CONFIG_HOME]"
@@ -46,24 +46,28 @@ info:
success: true
exit_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
+○ Available template variables
+  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_
+○ Expanding eval
+  {{ branch | hash_port }}
+  →
+  12107