Skip to content

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

refactor(for-each): exec argv directly, drop implicit shell (#2465)

Worktrunk Bot6eaf34971122
diff --git a/docs/content/extending.md b/docs/content/extending.md
index 7692ef18c..97aca07c0 100644
--- a/docs/content/extending.md
+++ b/docs/content/extending.md
@@ -122,7 +122,7 @@ Every step sees the same `{{ args }}` and bound variables — `wt release -- --d
```toml
[aliases]
up = '''
-git fetch --all --prune && wt step for-each -- '
+git fetch --all --prune && wt step for-each -- sh -c '
git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0
g=$(git rev-parse --git-dir)
test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0
diff --git a/docs/content/step.md b/docs/content/step.md
index 7100ba7fc..0e448beae 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -538,27 +538,27 @@ Run command in each worktree. Executes sequentially with real-time output; conti
A summary of successes and failures is shown at the end. Context JSON is piped to stdin for scripts that need structured data.
-### Template variables
+### Arguments
-All variables are shell-escaped. See [`wt hook` template variables](@/hook.md#template-variables) for the complete list and filters.
+Arguments after `--` are the program and its arguments — run directly, no shell.
-### Examples
+{{ terminal(cmd="wt step for-each -- git status --short|||wt step for-each -- npm install") }}
-Check status across all worktrees:
+For pipes, redirects, variables, or globs, wrap in `sh -c`:
-{{ terminal(cmd="wt step for-each -- git status --short") }}
+{{ terminal(cmd="wt step for-each -- sh -c 'git status | wc -l'|||wt step for-each -- sh -c 'echo $HOME && git pull'") }}
-Run npm install in all worktrees:
+### Template variables
-{{ terminal(cmd="wt step for-each -- npm install") }}
+Variables substitute into each argv element before exec. See [`wt hook` template variables](@/hook.md#template-variables) for the complete list and filters.
-Use branch name in command:
+{{ terminal(cmd="wt step for-each -- echo 'Branch: __WT_OPEN__ branch __WT_CLOSE__'") }}
-{{ terminal(cmd="wt step for-each -- __WT_QUOT__echo Branch: __WT_OPEN__ branch __WT_CLOSE____WT_QUOT__") }}
+### Examples
Pull updates in worktrees with upstreams (skips others):
-{{ terminal(cmd="git fetch --prune && wt step for-each -- '[ __WT_QUOT__$(git rev-parse @{u} 2>/dev/null)__WT_QUOT__ ] || exit 0; git pull --autostash'") }}
+{{ terminal(cmd="git fetch --prune && wt step for-each -- sh -c '[ __WT_QUOT__$(git rev-parse @{u} 2>/dev/null)__WT_QUOT__ ] || exit 0; git pull --autostash'") }}
Note: This command is experimental and may change in future versions.
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index 6e432b40a..ead05be9e 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -126,7 +126,7 @@ Every step sees the same `{{ args }}` and bound variables — `wt release -- --d
```toml
[aliases]
up = '''
-git fetch --all --prune && wt step for-each -- '
+git fetch --all --prune && wt step for-each -- sh -c '
git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0
g=$(git rev-parse --git-dir)
test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 14616f7ee..7ef627fb5 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -557,34 +557,36 @@ Run command in each worktree. Executes sequentially with real-time output; conti
A summary of successes and failures is shown at the end. Context JSON is piped to stdin for scripts that need structured data.
-### Template variables
-
-All variables are shell-escaped. See [`wt hook` template variables](https://worktrunk.dev/hook/#template-variables) for the complete list and filters.
+### Arguments
-### Examples
-
-Check status across all worktrees:
+Arguments after `--` are the program and its arguments — run directly, no shell.
```bash
$ wt step for-each -- git status --short
+$ wt step for-each -- npm install
```
-Run npm install in all worktrees:
+For pipes, redirects, variables, or globs, wrap in `sh -c`:
```bash
-$ wt step for-each -- npm install
+$ wt step for-each -- sh -c 'git status | wc -l'
+$ wt step for-each -- sh -c 'echo $HOME && git pull'
```
-Use branch name in command:
+### Template variables
+
+Variables substitute into each argv element before exec. See [`wt hook` template variables](https://worktrunk.dev/hook/#template-variables) for the complete list and filters.
```bash
-$ wt step for-each -- "echo Branch: {{ branch }}"
+$ wt step for-each -- echo 'Branch: {{ branch }}'
```
+### Examples
+
Pull updates in worktrees with upstreams (skips others):
```bash
-$ git fetch --prune && wt step for-each -- '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'
+$ git fetch --prune && wt step for-each -- sh -c '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'
```
Note: This command is experimental and may change in future versions.
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 67f1e41de..e154d4317 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -421,34 +421,36 @@ Note: This command is experimental and may change in future versions.
#[command(
after_long_help = r#"A summary of successes and failures is shown at the end. Context JSON is piped to stdin for scripts that need structured data.
-## Template variables
-
-All variables are shell-escaped. See [`wt hook` template variables](@/hook.md#template-variables) for the complete list and filters.
+## Arguments
-## Examples
-
-Check status across all worktrees:
+Arguments after `--` are the program and its arguments — run directly, no shell.
```console
$ wt step for-each -- git status --short
+$ wt step for-each -- npm install
```
-Run npm install in all worktrees:
+For pipes, redirects, variables, or globs, wrap in `sh -c`:
```console
-$ wt step for-each -- npm install
+$ wt step for-each -- sh -c 'git status | wc -l'
+$ wt step for-each -- sh -c 'echo $HOME && git pull'
```
-Use branch name in command:
+## Template variables
+
+Variables substitute into each argv element before exec. See [`wt hook` template variables](@/hook.md#template-variables) for the complete list and filters.
```console
-$ wt step for-each -- "echo Branch: {{ branch }}"
+$ wt step for-each -- echo 'Branch: {{ branch }}'
```
+## Examples
+
Pull updates in worktrees with upstreams (skips others):
```console
-$ git fetch --prune && wt step for-each -- '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'
+$ git fetch --prune && wt step for-each -- sh -c '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'
```
Note: This command is experimental and may change in future versions.
diff --git a/src/commands/for_each.rs b/src/commands/for_each.rs
index 13fd457bb..35a80e215 100644
--- a/src/commands/for_each.rs
+++ b/src/commands/for_each.rs
@@ -1,6 +1,9 @@
//! For-each command implementation
//!
-//! Runs a command sequentially in each worktree with template expansion.
+//! Runs a command sequentially in each worktree by direct exec — no implicit
+//! shell. Each post-`--` argv element is template-expanded and passed through
+//! to the program. Users wanting shell features (pipes, redirects, `$VAR`)
+//! pass `sh -c '<snippet>'` explicitly.
//!
//! # Design Notes
//!
@@ -21,25 +24,28 @@
//!
//! For now, we keep `for-each` under `step` as a pragmatic choice.
+use std::collections::HashMap;
+use std::io::{Write as _, stderr};
+use std::process::Stdio;
+
use color_print::cformat;
-use worktrunk::config::UserConfig;
+use worktrunk::config::{UserConfig, expand_template};
use worktrunk::git::{Repository, WorktreeInfo, WorktrunkError, interrupt_exit_code};
+use worktrunk::shell_exec::Cmd;
use worktrunk::styling::{
eprintln, error_message, format_with_gutter, progress_message, success_message, warning_message,
};
-use crate::commands::command_executor::{
- CommandContext, build_hook_context, expand_shell_template,
-};
+use crate::commands::command_executor::{CommandContext, build_hook_context};
use crate::commands::worktree_display_name;
-use crate::output::{DirectivePassthrough, execute_shell_command};
/// Run a command in each worktree sequentially.
///
-/// Executes the given command in every worktree, streaming output
-/// in real-time. Continues on errors and reports a summary at the end.
+/// Executes the given argv directly in every worktree, streaming output in
+/// real-time. Continues on errors and reports a summary at the end.
///
-/// All template variables from hooks are available, and context JSON is piped to stdin.
+/// All template variables from hooks are available; values are substituted
+/// into argv elements without shell escaping. Context JSON is piped to stdin.
pub fn step_for_each(args: Vec<String>, format: crate::cli::SwitchFormat) -> anyhow::Result<()> {
let json_mode = format == crate::cli::SwitchFormat::Json;
let repo = Repository::current()?;
@@ -59,9 +65,6 @@ pub fn step_for_each(args: Vec<String>, format: crate::cli::SwitchFormat) -> any
let mut interrupted: Option<i32> = None;
let total = worktrees.len();
- // Join args into a template string (will be expanded per-worktree)
- let command_template = args.join(" ");
-
for &wt in &worktrees {
let display_name = worktree_display_name(wt, &repo, &config);
eprintln!(
@@ -74,30 +77,23 @@ pub fn step_for_each(args: Vec<String>, format: crate::cli::SwitchFormat) -> any
let ctx = CommandContext::new(&repo, &config, wt.branch.as_deref(), &wt.path, false);
let context_map = build_hook_context(&ctx, &[])?;
- // Expand template with full context (shell-escaped)
- let command =
- expand_shell_template(&command_template, &context_map, &repo, "for-each command")?;
+ // Expand each argv element through the template engine without
+ // shell-escaping — values are interpolated directly into the argv
+ // element a program receives, not through `sh -c`.
+ let vars: HashMap<&str, &str> = context_map
+ .iter()
+ .map(|(k, v)| (k.as_str(), v.as_str()))
+ .collect();
+ let expanded: Vec<String> = args
+ .iter()
+ .map(|arg| expand_template(arg, &vars, false, &repo, "for-each argument"))
+ .collect::<Result<_, _>>()?;
// Build JSON context for stdin
let context_json = serde_json::to_string(&context_map)
.expect("HashMap<String, String> serialization should never fail");
- // Execute command: stream both stdout and stderr in real-time.
- // Pipe context JSON to stdin for scripts that want structured data.
- // Directive files are scrubbed — commands run in other worktrees should
- // not influence the parent shell's working directory.
- // for-each prints decorated headers/footers around child output, so
- // we merge child stdout onto stderr to keep ordering deterministic.
- // The structured `--format=json` output is a separate stdout write
- // emitted after all child commands complete (see below).
- match execute_shell_command(
- &wt.path,
- &command,
- Some(&context_json),
- None,
- DirectivePassthrough::none(),
- true,
- ) {
+ match run_argv(&wt.path, expanded, &context_json) {
Ok(()) => {
if json_mode {
json_results.push(serde_json::json!({
@@ -202,3 +198,42 @@ pub fn step_for_each(args: Vec<String>, format: crate::cli::SwitchFormat) -> any
Err(WorktrunkError::AlreadyDisplayed { exit_code: 1 }.into())
}
}
+
+/// Run argv directly (no shell) with streaming output, signal forwarding,
+/// stdout→stderr redirect, and JSON context piped on stdin.
+///
+/// Mirrors the bookkeeping in `output::execute_shell_command` (flush, ANSI
+/// reset, signal forwarding) but builds the command via `Cmd::new` so the
+/// program is exec'd directly without `sh -c` interposition. Directive env
+/// vars are scrubbed by `Cmd` for every spawn, so child commands run in
+/// other worktrees can't perturb the parent shell's CD/exec state.
+///
+/// Child stdout is merged onto stderr so it interleaves cleanly with
+/// for-each's decorated per-worktree headers and footers; the structured
+/// `--format=json` output is the only stdout write, emitted once after all
+/// children complete.
+fn run_argv(
+ working_dir: &std::path::Path,
+ argv: Vec<String>,
+ stdin_json: &str,
+) -> anyhow::Result<()> {
+ stderr().flush()?;
+ eprint!("{}", anstyle::Reset);
+ stderr().flush().ok();
+
+ let mut iter = argv.into_iter();
+ let program = iter
+ .next()
+ .expect("clap enforces at least one argv element");
+
+ Cmd::new(program)
+ .args(iter)
+ .current_dir(working_dir)
+ .stdout(Stdio::from(std::io::stderr()))
+ .forward_signals()
+ .stdin_bytes(stdin_json.as_bytes().to_vec())
+ .stream()?;
+
+ stderr().flush()?;
+ Ok(())
+}
diff --git a/src/output/concurrent.rs b/src/output/concurrent.rs
index 4cd7459a1..8ec5667e2 100644
--- a/src/output/concurrent.rs
+++ b/src/output/concurrent.rs
@@ -488,7 +488,7 @@ mod tests {
"job",
"true",
Some("test-label"),
- &DirectivePassthrough::none(),
+ &DirectivePassthrough::default(),
);
assert_eq!(outcomes.len(), 1);
assert!(outcomes[0].is_ok(), "`true` should exit 0");
diff --git a/src/output/handlers.rs b/src/output/handlers.rs
index c97c91abe..25081f244 100644
--- a/src/output/handlers.rs
+++ b/src/output/handlers.rs
@@ -1443,9 +1443,8 @@ fn handle_removed_worktree_output(
/// through (raw path, no injection surface); the EXEC file is never passed
/// through — only wt-internal Rust code writes arbitrary shell directives.
///
-/// - `DirectivePassthrough::none()` — scrubs all directive env vars from the
-/// child. Used by `for-each` (runs in other worktrees) and background hooks
-/// (outlive the parent shell).
+/// - `DirectivePassthrough::default()` — scrubs all directive env vars from
+/// the child. Used by background hooks (outlive the parent shell).
/// - `DirectivePassthrough::inherit_from_env()` — re-adds whichever directive
/// env vars are currently set in this process. Used by aliases and
/// foreground hooks, which may emit `cd` directives. In new-protocol mode
@@ -1528,10 +1527,11 @@ pub fn execute_shell_command(
/// Selector for which directive file env vars to pass through to a child shell.
///
-/// Constructed by callers via [`DirectivePassthrough::none`] or
-/// [`DirectivePassthrough::inherit_from_env`]. The EXEC file is intentionally
-/// never included — alias/hook shell bodies must not inject arbitrary shell
-/// into the parent session.
+/// `Default` (no fields set) scrubs all directive env vars from the child;
+/// [`DirectivePassthrough::inherit_from_env`] reads the current process
+/// environment for trusted contexts. The EXEC file is intentionally never
+/// included — alias/hook shell bodies must not inject arbitrary shell into
+/// the parent session.
#[derive(Debug, Default, Clone)]
pub struct DirectivePassthrough {
pub cd_file: Option<std::path::PathBuf>,
@@ -1539,11 +1539,6 @@ pub struct DirectivePassthrough {
}
impl DirectivePassthrough {
- /// Scrub all directive file env vars from the child process.
- pub fn none() -> Self {
- Self::default()
- }
-
/// Pass CD and legacy directive files through to the child, reading the
/// current process environment. Used by trusted contexts (aliases,
/// foreground hooks) that may legitimately emit a `cd` directive. The
diff --git a/tests/integration_tests/for_each.rs b/tests/integration_tests/for_each.rs
index 2d36caba2..aeb40df52 100644
--- a/tests/integration_tests/for_each.rs
+++ b/tests/integration_tests/for_each.rs
@@ -84,44 +84,82 @@ fn test_for_each_detached_branch_variable(mut repo: TestRepo) {
fn test_for_each_spawn_fails(mut repo: TestRepo) {
repo.add_worktree("feature");
- assert_cmd_snapshot!(make_snapshot_cmd(
- &repo,
- "step",
- &["for-each", "--", "nonexistent-command-12345", "--some-arg"],
- None,
- ));
+ // Normalize platform-specific spawn-error text so the snapshot is
+ // identical on Unix (`No such file or directory (os error 2)`) and
+ // Windows (`program not found`).
+ insta::with_settings!({
+ filters => vec![
+ (r"No such file or directory \(os error \d+\)", "[SPAWN_FAIL]"),
+ (r"program not found", "[SPAWN_FAIL]"),
+ ],
+ }, {
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["for-each", "--", "nonexistent-command-12345", "--some-arg"],
+ None,
+ ));
+ });
}
-/// Force the shell spawn itself to fail (rather than the command inside the
-/// shell exiting non-zero) by setting `PATH` to a directory that contains
-/// only `git` (so wt can still operate) but no `sh` (so the child shell
-/// spawn fails). This is the only branch in the failure handler that does
-/// NOT downcast to `WorktrunkError::ChildProcessExited`, and it appears in
-/// JSON mode as `exit_code: null`. Without this test the spawn-failed JSON
-/// path is unreachable from the integration suite (#2089 review).
+/// argv boundaries from the post-`--` args reach the program intact. The
+/// command is exec'd directly — no implicit shell — so each argv element
+/// arrives at the child as a single argument regardless of its content.
+/// See issue #2461 for the legacy bug where joining argv into `sh -c`
+/// collapsed `python3 -c 'import sys; print(sys.argv[1:])' 'a b'` into a
+/// shell syntax error.
#[rstest]
#[cfg(unix)]
-fn test_for_each_json_spawn_failure(repo: TestRepo) {
- use std::path::PathBuf;
-
- // Locate a real `git` so we can symlink it into the minimal PATH dir.
- // wt itself shells out to git constantly; clearing PATH entirely makes
- // wt fail before it ever reaches the shell-spawn branch we want to test.
- let git_path: PathBuf = std::env::var_os("PATH")
- .iter()
- .flat_map(std::env::split_paths)
- .map(|p| p.join("git"))
- .find(|p| p.is_file())
- .expect("git must be in PATH for tests");
-
- let tmp = tempfile::tempdir().expect("create tmpdir for minimal PATH");
- std::os::unix::fs::symlink(&git_path, tmp.path().join("git"))
- .expect("symlink git into minimal PATH");
- // Deliberately do NOT symlink `sh` — that's what makes the shell spawn fail.
+fn test_for_each_preserves_argv_quoting(repo: TestRepo) {
+ let output = repo
+ .wt_command()
+ .args([
+ "step",
+ "for-each",
+ "--",
+ "python3",
+ "-c",
+ "import sys; print(sys.argv[1:])",
+ "a b",
+ ])
+ .output()
+ .expect("run wt step for-each");
+ let combined = format!(
+ "{}{}",
+ String::from_utf8_lossy(&output.stdout),
+ String::from_utf8_lossy(&output.stderr),
+ );
+ assert!(
+ output.status.success(),
+ "for-each should succeed when argv quoting is preserved: {combined}",
+ );
+ assert!(
+ combined.contains("['a b']"),
+ "expected python to receive 'a b' as a single argv element, got: {combined}",
+ );
+ assert!(
+ !combined.contains("Syntax error"),
+ "for-each should not produce shell syntax errors when argv has quoted args: {combined}",
+ );
+}
+
+/// Spawn failure (program not found) is the one branch in the failure
+/// handler that does NOT downcast to `WorktrunkError::ChildProcessExited`,
+/// and it appears in JSON mode as `exit_code: null`. Without this test the
+/// spawn-failed JSON path is unreachable from the integration suite
+/// (#2089 review).
+#[rstest]
+#[cfg(unix)]
+fn test_for_each_json_spawn_failure(repo: TestRepo) {
let mut cmd = repo.wt_command();
- cmd.env("PATH", tmp.path());
- cmd.args(["step", "for-each", "--format=json", "--", "true"]);
+ cmd.args([
+ "step",
+ "for-each",
+ "--format=json",
+ "--",
+ "nonexistent-command-12345",
+ ]);
let output = cmd.output().unwrap();
assert!(
@@ -170,19 +208,17 @@ fn test_for_each_aborts_on_signal_exit(repo: TestRepo) {
// so we just need the command to abort on the first visit.
// A marker file per visited worktree lets us assert that the loop stopped
- // after the first signal. for-each joins the post-`--` args with spaces
- // and runs the result through `sh -c`; we pass shell fragments that
- // touch a marker and then self-signal with SIGTERM.
+ // after the first signal. for-each exec's argv directly with no implicit
+ // shell, so shell features (`&&`, `$$`, `$(...)`) need an explicit
+ // `sh -c` invocation.
let marker_dir = tempfile::tempdir().expect("create marker tmpdir");
let marker_path = marker_dir.path().to_string_lossy().to_string();
- let touch_cmd = format!("touch {marker_path}/$(basename \"$(pwd)\")");
+ let shell_cmd = format!("touch {marker_path}/$(basename \"$(pwd)\") && kill -TERM $$");
let output = repo
.wt_command()
- .args([
- "step", "for-each", "--", &touch_cmd, "&&", "kill", "-TERM", "$$",
- ])
+ .args(["step", "for-each", "--", "sh", "-c", &shell_cmd])
.output()
.expect("run wt step for-each");
diff --git a/tests/snapshots/integration__integration_tests__for_each__for_each_spawn_fails.snap b/tests/snapshots/integration__integration_tests__for_each__for_each_spawn_fails.snap
index 9d9338f34..5501c1232 100644
--- a/tests/snapshots/integration__integration_tests__for_each__for_each_spawn_fails.snap
+++ b/tests/snapshots/integration__integration_tests__for_each__for_each_spawn_fails.snap
@@ -48,20 +48,20 @@ exit_code: 1
----- stderr -----
◎ Running in main...
-sh: nonexistent-command-12345: command not found
-✗ Failed in main (exit code 127)
+✗ Failed in main (spawn failed)
+  ✗ Failed to execute command (direct): [SPAWN_FAIL]
◎ Running in feature...
-sh: nonexistent-command-12345: command not found
-✗ Failed in feature (exit code 127)
+✗ Failed in feature (spawn failed)
+  ✗ Failed to execute command (direct): [SPAWN_FAIL]
◎ Running in feature-a...
-sh: nonexistent-command-12345: command not found
-✗ Failed in feature-a (exit code 127)
+✗ Failed in feature-a (spawn failed)
+  ✗ Failed to execute command (direct): [SPAWN_FAIL]
◎ Running in feature-b...
-sh: nonexistent-command-12345: command not found
-✗ Failed in feature-b (exit code 127)
+✗ Failed in feature-b (spawn failed)
+  ✗ Failed to execute command (direct): [SPAWN_FAIL]
◎ Running in feature-c...
-sh: nonexistent-command-12345: command not found
-✗ Failed in feature-c (exit code 127)
+✗ Failed in feature-c (spawn failed)
+  ✗ Failed to execute command (direct): [SPAWN_FAIL]
▲ 5 of 5 worktrees failed
  main