Struct Cmd 

pub struct Cmd { /* private fields */ }

Builder for executing commands with two modes of operation.

• .run() — captures output, provides logging/semaphore/tracing
• .stream() — inherits stdout/stderr for TTY preservation (hooks, interactive); stdin defaults to null unless configured with .stdin(Stdio) or .stdin_bytes()

Examples

Capture output:

let output = Cmd::new("git")
    .args(["status", "--porcelain"])
    .current_dir(&repo_path)
    .context("my-worktree")
    .run()?;

Stream output (hooks, interactive):

use std::process::Stdio;

Cmd::shell("npm run build")
    .current_dir(&repo_path)
    .stdout(Stdio::from(std::io::stderr()))
    .forward_signals()
    .stream()?;

Implementations

impl Cmd

pub fn new(program: impl Into<String>) -> Self

Create a new command builder for the given program.

The program is executed directly without shell interpretation. For shell commands (with pipes, redirects, etc.), use Cmd::shell().

pub fn shell(command: impl Into<String>) -> Self

Create a command builder for a shell command string.

The command is executed through the platform’s shell (sh -c on Unix, Git Bash on Windows), enabling shell features like pipes and redirects.

Only valid with .stream() — shell commands cannot use .run().

pub fn arg(self, arg: impl Into<String>) -> Self

Add a single argument.

pub fn args<I, S>(self, args: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Add multiple arguments.

pub fn current_dir(self, dir: impl Into<PathBuf>) -> Self

Set the working directory for the command.

pub fn context(self, ctx: impl Into<String>) -> Self

Set the logging context (typically worktree name for git commands).

pub fn stdin_bytes(self, data: impl Into<Vec<u8>>) -> Self

Set data to pipe to the command’s stdin.

For .run(), the data is written to a piped stdin. For .stream(), this takes precedence over .stdin(Stdio).

pub fn timeout(self, duration: Duration) -> Self

Set a timeout for command execution (only applies to .run()).

Note: Timeout is not supported by .stream() since streaming commands are interactive and should not be time-limited.

pub fn env(self, key: impl AsRef<OsStr>, val: impl AsRef<OsStr>) -> Self

Set an environment variable.

Accepts the same types as Command::env: string literals, String, &Path, PathBuf, OsString, etc.

pub fn env_remove(self, key: impl AsRef<OsStr>) -> Self

Remove an environment variable.

pub fn stdout(self, cfg: Stdio) -> Self

Set stdout configuration for .stream().

Defaults to Stdio::inherit(). Use Stdio::from(io::stderr()) to redirect stdout to stderr for deterministic output ordering.

Only affects .stream(). For .run(), output is always captured separately.

pub fn stdin(self, cfg: Stdio) -> Self

Set stdin configuration for .stream().

Defaults to Stdio::null(). Use Stdio::inherit() for interactive commands that need to read user input.

Only affects .stream(). For .run(), stdin defaults to null unless data is provided via .stdin_bytes().

pub fn forward_signals(self) -> Self

Forward signals (SIGINT, SIGTERM) to child process group.

On Unix, spawns the child in its own process group and forwards signals with escalation (SIGINT → SIGTERM → SIGKILL). This enables clean shutdown of the entire process tree on Ctrl-C.

Only affects .stream() on Unix. No-op on Windows.

pub fn external(self, label: impl Into<String>) -> Self

Mark this command as an external (user-configured) command for logging.

When set, the command execution is logged to .git/wt/logs/commands.jsonl with the given label (e.g., “pre-merge user:lint”, “commit.generation”).

pub fn run(self) -> Result<Output>

Execute the command and return its output.

Captures stdout/stderr and returns them in Output. For interactive commands or hooks where output should stream to the terminal, use .stream() instead.

Panics

Panics if called on a shell-wrapped command (created via Cmd::shell()). Shell commands must use .stream() because they need TTY preservation.

pub fn stream(self) -> Result<()>

Execute the command with streaming output (inherits stdio).

Unlike .run(), this method:

• Inherits stderr to preserve TTY behavior (colors, progress bars)
• Optionally redirects stdout to stderr (via .stdout(Stdio::from(io::stderr())))
• Optionally inherits stdin for interactive commands (via .stdin(Stdio::inherit()))
• Optionally forwards signals to child process group (via .forward_signals())
• Does not use concurrency limiting (streaming commands run sequentially by nature)
• Does not support timeout (interactive commands should not be time-limited)

Shell commands created via Cmd::shell() are executed through the platform’s shell (sh -c on Unix, Git Bash on Windows).

Returns error if command exits with non-zero status.