Skip to content

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

refactor(expand): label -v template expansion as source/result blocks (#3099)

Maximilian Roos01242177d3d1
diff --git a/.claude/skills/writing-user-outputs/SKILL.md b/.claude/skills/writing-user-outputs/SKILL.md
index fc041bbbc..dc3c1ba30 100644
--- a/.claude/skills/writing-user-outputs/SKILL.md
+++ b/.claude/skills/writing-user-outputs/SKILL.md
@@ -925,20 +925,26 @@ See `src/git/error.rs` for examples of this pattern in `GitError` Display impls.
**`-v` (verbose):** User-facing diagnostic output. Must follow these guidelines.
Shows template expansions and other details users might need for debugging config.
-Format for template expansion:
-```
-○ Expanding name
- ┃ template (bash-highlighted)
- ┃ → (dim)
- ┃ result (bash-highlighted)
-```
-
-- **Info message** for header (`○` symbol, "Expanding" + bold name)
-- **Bash gutter** for template and result (dim + syntax highlighting via
- `format_bash_with_gutter`)
-- **Plain gutter** for dim `→` separator (bypasses syntax highlighter)
-- Template and result are always on separate gutter blocks from the arrow,
- because the `→` can't go through the bash syntax highlighter
+Template expansion shows the source template and the rendered result as two
+labeled blocks. Each block is a bash gutter (dim + syntax highlighting via
+`format_bash_with_gutter`) under its own info header (`○` symbol, bold name,
+then `source` or `result`):
+```
+○ name source
+ ┃ template
+○ name result
+ ┃ result
+```
+
+The two headers carry the input/output distinction, so both blocks share the
+same gutter and the content always starts at the gutter's column 2 (no marker
+glyph or extra indent inside the gutter). Multi-line templates and results
+follow the same shape, one gutter line per source line.
+
+`expand_template` emits no trailing blank, so a standalone caller adds one to
+separate the block from what follows (`wt step eval` does this after the view).
+In a command pipeline the executor already separates the block from the next
+output, so the expansion adds nothing.
**`-vv` (debug):** Developer-facing logging output. MAY violate these guidelines.
Uses `log::debug!()` with structured format for deep debugging. Not intended for
diff --git a/docs/content/step.md b/docs/content/step.md
index bbd00ea7e..217fef054 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -540,10 +540,11 @@ List the available template variables with `-v` (alongside the expansion, on std
○ Available template variables
branch = feature/auth-oauth2
worktree_path = /home/user/projects/myapp-feature-auth-oauth2
-○ Expanding eval
+○ eval source
{{ branch }}
- →
+○ eval result
feature/auth-oauth2
+
feature/auth-oauth2
{% end %}
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 965adf0c1..3d82fb56b 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -557,10 +557,11 @@ $ wt step eval -v '{{ branch }}'
○ Available template variables
branch = feature/auth-oauth2
worktree_path = /home/user/projects/myapp-feature-auth-oauth2
-○ Expanding eval
+○ eval source
{{ branch }}
- →
+○ eval result
feature/auth-oauth2
+
feature/auth-oauth2
```
diff --git a/src/cli/step.rs b/src/cli/step.rs
index ce8c06009..7fd5cca7b 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -438,10 +438,11 @@ $ wt step eval -v '{{ branch }}'
○ Available template variables
branch = feature/auth-oauth2
worktree_path = /home/user/projects/myapp-feature-auth-oauth2
-○ Expanding eval
+○ eval source
{{ branch }}
- →
+○ eval result
feature/auth-oauth2
+
feature/auth-oauth2
```
diff --git a/src/commands/eval.rs b/src/commands/eval.rs
index 6006238f6..3c0e13b5f 100644
--- a/src/commands/eval.rs
+++ b/src/commands/eval.rs
@@ -20,7 +20,7 @@ use crate::commands::command_executor::{CommandContext, build_hook_context};
///
/// `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
+/// stderr, above the labeled `source` / `result` expansion view that
/// `expand_template` renders at `-v`.
pub fn step_eval(template: &str) -> anyhow::Result<()> {
let repo = Repository::current()?;
@@ -55,6 +55,11 @@ pub fn step_eval(template: &str) -> anyhow::Result<()> {
.collect();
let result = expand_template(template, &vars, ShellEscapeMode::Literal, &repo, "eval")?;
+ // `expand_template` emitted the `source` / `result` view to stderr under
+ // `-v`; a trailing blank separates it from the result printed below.
+ if verbosity() >= 1 {
+ eprintln!();
+ }
println!("{result}");
Ok(())
}
diff --git a/src/config/expansion.rs b/src/config/expansion.rs
index 636e29d41..1a49afd46 100644
--- a/src/config/expansion.rs
+++ b/src/config/expansion.rs
@@ -1038,17 +1038,19 @@ pub fn expand_template(
log::debug!("[template:{name}] result={:?}", redact_credentials(&result));
}
- // -v: Nice styled output showing template expansion
- // Info message for header, gutter for quoted content (template → result)
+ // -v: Nice styled output showing template expansion. The source template
+ // and the rendered result each get a labeled info header above a bash gutter
+ // block, so the eye separates input from output. Callers that emit several
+ // expansions in a row (or a single standalone one, like `wt step eval`) add
+ // a trailing blank to separate them; in a command pipeline the executor
+ // already provides that separation.
// Single atomic write to avoid interleaving in multi-threaded execution
if verbose == 1 {
- let header = info_message(cformat!("Expanding <bold>{name}</>"));
- // Format template and result as bash (dim + syntax highlighting),
- // with a dim → separator that bypasses the syntax highlighter
- let template_gutter = format_bash_with_gutter(template);
- let arrow = format_with_gutter(&cformat!("<dim>→</>"), None);
+ let source_header = info_message(cformat!("<bold>{name}</> source"));
+ let source_gutter = format_bash_with_gutter(template);
+ let result_header = info_message(cformat!("<bold>{name}</> result"));
let result_gutter = format_bash_with_gutter(&result);
- eprintln!("{header}\n{template_gutter}\n{arrow}\n{result_gutter}");
+ eprintln!("{source_header}\n{source_gutter}\n{result_header}\n{result_gutter}");
}
Ok(result)
}
diff --git a/tests/snapshots/integration__integration_tests__config_show__deprecated_template_variables_verbose_shows_content.snap b/tests/snapshots/integration__integration_tests__config_show__deprecated_template_variables_verbose_shows_content.snap
index 777a4dd59..16531ca54 100644
--- a/tests/snapshots/integration__integration_tests__config_show__deprecated_template_variables_verbose_shows_content.snap
+++ b/tests/snapshots/integration__integration_tests__config_show__deprecated_template_variables_verbose_shows_content.snap
@@ -57,15 +57,15 @@ exit_code: 0
▲ User config: template variable worktree is deprecated in favor of worktree_path
▲ User config: template variable main_worktree is deprecated in favor of repo
↳ To see details, run wt config show; to apply updates, run wt config update
-○ Expanding worktree-path
+○ worktree-path source
  ../{{ main_worktree }}.{{ branch }}
-  →
+○ worktree-path result
  ../repo.feature-a
-○ Expanding worktree-path
+○ worktree-path source
  ../{{ main_worktree }}.{{ branch }}
-  →
+○ worktree-path result
  ../repo.feature-b
-○ Expanding worktree-path
+○ worktree-path source
  ../{{ main_worktree }}.{{ branch }}
-  →
+○ worktree-path result
  ../repo.feature-c
diff --git a/tests/snapshots/integration__integration_tests__eval__eval_verbose.snap b/tests/snapshots/integration__integration_tests__eval__eval_verbose.snap
index 0e1d14fbe..6331f4e6e 100644
--- a/tests/snapshots/integration__integration_tests__eval__eval_verbose.snap
+++ b/tests/snapshots/integration__integration_tests__eval__eval_verbose.snap
@@ -67,7 +67,7 @@ exit_code: 0
  worktree = _REPO_
  worktree_name = repo
  worktree_path = _REPO_
-○ Expanding eval
+○ eval source
  {{ branch | hash_port }}
-  →
+○ eval result
  12107
diff --git a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_output.snap b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_output.snap
index 75f01af2e..43d4a6fcc 100644
--- a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_output.snap
+++ b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_output.snap
@@ -48,9 +48,9 @@ exit_code: 0
----- stdout -----
----- stderr -----
-○ Expanding worktree-path
+○ worktree-path source
  {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}
-  →
+○ worktree-path result
  _REPO_/../repo.feature
✓ Created branch feature from main and worktree @ _REPO_.feature
↳ To customize worktree locations, run wt config create
diff --git a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_template_expansion.snap b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_template_expansion.snap
index 7f5a5a8d5..801da48b3 100644
--- a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_template_expansion.snap
+++ b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_template_expansion.snap
@@ -48,13 +48,13 @@ exit_code: 0
----- stdout -----
----- stderr -----
-○ Expanding worktree-path
+○ worktree-path source
  ../{{ repo }}.{{ branch | sanitize }}
-  →
+○ worktree-path result
  ../repo.verbose-hooks
-○ Expanding project:setup
+○ project:setup source
  echo 'Setting up {{ branch | sanitize }} in {{ worktree_path }}'
-  →
+○ project:setup result
  echo 'Setting up verbose-hooks in _REPO_.verbose-hooks'
○ template variables:
  branch = verbose-hooks
diff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_verbose_args_shell_escaped.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_verbose_args_shell_escaped.snap
index 70e3eccf2..4bd1f29c2 100644
--- a/tests/snapshots/integration__integration_tests__step_alias__alias_verbose_args_shell_escaped.snap
+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_verbose_args_shell_escaped.snap
@@ -66,8 +66,8 @@ hello foo bar baz
  cwd = _REPO_.feature
  args = foo 'bar baz'
◎ Running alias greet
-○ Expanding greet
+○ greet source
  echo hello {{ args }}
-  →
+○ greet result
  echo hello foo 'bar baz'

diff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_verbose_variable_table.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_verbose_variable_table.snap
index 3ced1efa9..133928cef 100644
--- a/tests/snapshots/integration__integration_tests__step_alias__alias_verbose_variable_table.snap
+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_verbose_variable_table.snap
@@ -65,8 +65,8 @@ hello world
  cwd = _REPO_.feature
  args = world
◎ Running alias greet
-○ Expanding greet
+○ greet source
  echo hello {{ args }}
-  →
+○ greet result
  echo hello world

diff --git a/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_multiline_template.snap b/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_multiline_template.snap
index 5a134837d..1d0c3032a 100644
--- a/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_multiline_template.snap
+++ b/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_multiline_template.snap
@@ -52,9 +52,9 @@ branch=multiline-test
repo=repo
----- stderr -----
-○ Expanding worktree-path
+○ worktree-path source
  {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}
-  →
+○ worktree-path result
  _REPO_/../repo.multiline-test
▲ --execute will change in a future release: it will run a single program, with arguments after --, not a shell command line
↳ Comment at https://github.com/max-sixty/worktrunk/issues/2860 if the new single-program form would make a workflow worse; to run this command line unchanged, pass it to a shell: --execute sh -- -c '{% if branch %}
@@ -65,12 +65,12 @@ echo '\''repo={{ repo }}'\''
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — shell integration not installed
↳ To enable automatic cd, run wt config shell install
-○ Expanding --execute command
+○ --execute command source
  {% if branch %}
  echo 'branch={{ branch }}'
  echo 'repo={{ repo }}'
  {% endif %}
-  →
+○ --execute command result
  
  echo 'branch=multiline-test'
  echo 'repo=repo'
diff --git a/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_template.snap b/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_template.snap
index 996a7af45..238b7d5c3 100644
--- a/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_template.snap
+++ b/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_template.snap
@@ -51,9 +51,9 @@ exit_code: 0
branch=verbose-test
----- stderr -----
-○ Expanding worktree-path
+○ worktree-path source
  {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}
-  →
+○ worktree-path result
  _REPO_/../repo.verbose-test
▲ --execute will change in a future release: it will run a single program, with arguments after --, not a shell command line
↳ Comment at https://github.com/max-sixty/worktrunk/issues/2860 if the new single-program form would make a workflow worse; to run this command line unchanged, pass it to a shell: --execute sh -- -c 'echo '\''branch={{ branch }}'\'''
@@ -61,9 +61,9 @@ branch=verbose-test
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — shell integration not installed
↳ To enable automatic cd, run wt config shell install
-○ Expanding --execute command
+○ --execute command source
  echo 'branch={{ branch }}'
-  →
+○ --execute command result
  echo 'branch=verbose-test'
◎ Executing (--execute) @ _REPO_.verbose-test:
  echo 'branch=verbose-test'
diff --git a/tests/snapshots/integration__integration_tests__user_hooks__combined_post_remove_and_post_switch_verbose.snap b/tests/snapshots/integration__integration_tests__user_hooks__combined_post_remove_and_post_switch_verbose.snap
index 17ae5adfd..3436531d2 100644
--- a/tests/snapshots/integration__integration_tests__user_hooks__combined_post_remove_and_post_switch_verbose.snap
+++ b/tests/snapshots/integration__integration_tests__user_hooks__combined_post_remove_and_post_switch_verbose.snap
@@ -48,9 +48,9 @@ exit_code: 0
----- stdout -----
----- stderr -----
-○ Expanding worktree-path
+○ worktree-path source
  {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}
-  →
+○ worktree-path result
  _REPO_/../repo.feature
◎ Removing feature worktree & branch in background (--force-delete)
▲ Cannot change directory — shell integration not installed
diff --git a/tests/snapshots/integration__integration_tests__user_hooks__hook_verbose_background_dedup.snap b/tests/snapshots/integration__integration_tests__user_hooks__hook_verbose_background_dedup.snap
index 388c50096..848d57dfd 100644
--- a/tests/snapshots/integration__integration_tests__user_hooks__hook_verbose_background_dedup.snap
+++ b/tests/snapshots/integration__integration_tests__user_hooks__hook_verbose_background_dedup.snap
@@ -48,9 +48,9 @@ exit_code: 0
----- stdout -----
----- stderr -----
-○ Expanding worktree-path
+○ worktree-path source
  {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}
-  →
+○ worktree-path result
  _REPO_/../repo.feature
✓ Created branch feature from main and worktree @ _REPO_.feature
↳ To customize worktree locations, run wt config create
diff --git a/tests/snapshots/integration__integration_tests__user_hooks__hook_verbose_variable_table.snap b/tests/snapshots/integration__integration_tests__user_hooks__hook_verbose_variable_table.snap
index 5f59119e0..9473c62ca 100644
--- a/tests/snapshots/integration__integration_tests__user_hooks__hook_verbose_variable_table.snap
+++ b/tests/snapshots/integration__integration_tests__user_hooks__hook_verbose_variable_table.snap
@@ -47,9 +47,9 @@ exit_code: 0
----- stdout -----
----- stderr -----
-○ Expanding user:noop
+○ user:noop source
  true
-  →
+○ user:noop result
  true
○ template variables:
  branch = feature
@@ -76,9 +76,9 @@ exit_code: 0
  hook_name = noop
◎ Running pre-switch user:noop
  true
-○ Expanding worktree-path
+○ worktree-path source
  {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}
-  →
+○ worktree-path result
  _REPO_/../repo.feature
▲ Worktree for feature @ _REPO_.feature, but cannot change directory — shell integration not installed
↳ To enable automatic cd, run wt config shell install