pub struct Command { /* private fields */ }
blob
only.Expand description
The outcome of a prepare_diff_command
operation.
This type acts like std::process::Command
, ready to run, with stdin
, stdout
and stderr
set to inherit
all handles as this is expected to be for visual inspection.
Methods from Deref<Target = Command>§
1.0.0 · sourcepub fn arg<S>(&mut self, arg: S) -> &mut Command
pub fn arg<S>(&mut self, arg: S) -> &mut Command
Adds an argument to pass to the program.
Only one argument can be passed per use. So instead of:
.arg("-C /path/to/repo")
usage would be:
.arg("-C")
.arg("/path/to/repo")
To pass multiple arguments see args
.
Note that the argument is not passed through a shell, but given literally to the program. This means that shell syntax like quotes, escaped characters, word splitting, glob patterns, variable substitution, etc. have no effect.
On Windows, use caution with untrusted inputs. Most applications use the
standard convention for decoding arguments passed to them. These are safe to
use with arg
. However, some applications such as cmd.exe
and .bat
files
use a non-standard way of decoding arguments. They are therefore vulnerable
to malicious input.
In the case of cmd.exe
this is especially important because a malicious
argument can potentially run arbitrary shell commands.
See Windows argument splitting for more details
or raw_arg
for manually implementing non-standard argument encoding.
§Examples
Basic usage:
use std::process::Command;
Command::new("ls")
.arg("-l")
.arg("-a")
.spawn()
.expect("ls command failed to start");
1.0.0 · sourcepub fn args<I, S>(&mut self, args: I) -> &mut Command
pub fn args<I, S>(&mut self, args: I) -> &mut Command
Adds multiple arguments to pass to the program.
To pass a single argument see arg
.
Note that the arguments are not passed through a shell, but given literally to the program. This means that shell syntax like quotes, escaped characters, word splitting, glob patterns, variable substitution, etc. have no effect.
On Windows, use caution with untrusted inputs. Most applications use the
standard convention for decoding arguments passed to them. These are safe to
use with arg
. However, some applications such as cmd.exe
and .bat
files
use a non-standard way of decoding arguments. They are therefore vulnerable
to malicious input.
In the case of cmd.exe
this is especially important because a malicious
argument can potentially run arbitrary shell commands.
See Windows argument splitting for more details
or raw_arg
for manually implementing non-standard argument encoding.
§Examples
Basic usage:
use std::process::Command;
Command::new("ls")
.args(["-l", "-a"])
.spawn()
.expect("ls command failed to start");
1.0.0 · sourcepub fn env<K, V>(&mut self, key: K, val: V) -> &mut Command
pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Command
Inserts or updates an explicit environment variable mapping.
This method allows you to add an environment variable mapping to the spawned process or
overwrite a previously set value. You can use Command::envs
to set multiple environment
variables simultaneously.
Child processes will inherit environment variables from their parent process by default.
Environment variables explicitly set using Command::env
take precedence over inherited
variables. You can disable environment variable inheritance entirely using
Command::env_clear
or for a single key using Command::env_remove
.
Note that environment variable names are case-insensitive (but case-preserving) on Windows and case-sensitive on all other platforms.
§Examples
Basic usage:
use std::process::Command;
Command::new("ls")
.env("PATH", "/bin")
.spawn()
.expect("ls command failed to start");
1.19.0 · sourcepub fn envs<I, K, V>(&mut self, vars: I) -> &mut Command
pub fn envs<I, K, V>(&mut self, vars: I) -> &mut Command
Inserts or updates multiple explicit environment variable mappings.
This method allows you to add multiple environment variable mappings to the spawned process
or overwrite previously set values. You can use Command::env
to set a single environment
variable.
Child processes will inherit environment variables from their parent process by default.
Environment variables explicitly set using Command::envs
take precedence over inherited
variables. You can disable environment variable inheritance entirely using
Command::env_clear
or for a single key using Command::env_remove
.
Note that environment variable names are case-insensitive (but case-preserving) on Windows and case-sensitive on all other platforms.
§Examples
Basic usage:
use std::process::{Command, Stdio};
use std::env;
use std::collections::HashMap;
let filtered_env : HashMap<String, String> =
env::vars().filter(|&(ref k, _)|
k == "TERM" || k == "TZ" || k == "LANG" || k == "PATH"
).collect();
Command::new("printenv")
.stdin(Stdio::null())
.stdout(Stdio::inherit())
.env_clear()
.envs(&filtered_env)
.spawn()
.expect("printenv failed to start");
1.0.0 · sourcepub fn env_remove<K>(&mut self, key: K) -> &mut Command
pub fn env_remove<K>(&mut self, key: K) -> &mut Command
Removes an explicitly set environment variable and prevents inheriting it from a parent process.
This method will remove the explicit value of an environment variable set via
Command::env
or Command::envs
. In addition, it will prevent the spawned child
process from inheriting that environment variable from its parent process.
After calling Command::env_remove
, the value associated with its key from
Command::get_envs
will be None
.
To clear all explicitly set environment variables and disable all environment variable
inheritance, you can use Command::env_clear
.
§Examples
Basic usage:
use std::process::Command;
Command::new("ls")
.env_remove("PATH")
.spawn()
.expect("ls command failed to start");
1.0.0 · sourcepub fn env_clear(&mut self) -> &mut Command
pub fn env_clear(&mut self) -> &mut Command
Clears all explicitly set environment variables and prevents inheriting any parent process environment variables.
This method will remove all explicitly added environment variables set via Command::env
or Command::envs
. In addition, it will prevent the spawned child process from inheriting
any environment variable from its parent process.
After calling Command::env_clear
, the iterator from Command::get_envs
will be
empty.
You can use Command::env_remove
to clear a single mapping.
§Examples
Basic usage:
use std::process::Command;
Command::new("ls")
.env_clear()
.spawn()
.expect("ls command failed to start");
1.0.0 · sourcepub fn current_dir<P>(&mut self, dir: P) -> &mut Command
pub fn current_dir<P>(&mut self, dir: P) -> &mut Command
Sets the working directory for the child process.
§Platform-specific behavior
If the program path is relative (e.g., "./script.sh"
), it’s ambiguous
whether it should be interpreted relative to the parent’s working
directory or relative to current_dir
. The behavior in this case is
platform specific and unstable, and it’s recommended to use
canonicalize
to get an absolute program path instead.
§Examples
Basic usage:
use std::process::Command;
Command::new("ls")
.current_dir("/bin")
.spawn()
.expect("ls command failed to start");
1.0.0 · sourcepub fn stdin<T>(&mut self, cfg: T) -> &mut Command
pub fn stdin<T>(&mut self, cfg: T) -> &mut Command
Configuration for the child process’s standard input (stdin) handle.
Defaults to inherit
when used with spawn
or status
, and
defaults to piped
when used with output
.
§Examples
Basic usage:
use std::process::{Command, Stdio};
Command::new("ls")
.stdin(Stdio::null())
.spawn()
.expect("ls command failed to start");
1.0.0 · sourcepub fn stdout<T>(&mut self, cfg: T) -> &mut Command
pub fn stdout<T>(&mut self, cfg: T) -> &mut Command
Configuration for the child process’s standard output (stdout) handle.
Defaults to inherit
when used with spawn
or status
, and
defaults to piped
when used with output
.
§Examples
Basic usage:
use std::process::{Command, Stdio};
Command::new("ls")
.stdout(Stdio::null())
.spawn()
.expect("ls command failed to start");
1.0.0 · sourcepub fn stderr<T>(&mut self, cfg: T) -> &mut Command
pub fn stderr<T>(&mut self, cfg: T) -> &mut Command
Configuration for the child process’s standard error (stderr) handle.
Defaults to inherit
when used with spawn
or status
, and
defaults to piped
when used with output
.
§Examples
Basic usage:
use std::process::{Command, Stdio};
Command::new("ls")
.stderr(Stdio::null())
.spawn()
.expect("ls command failed to start");
1.0.0 · sourcepub fn spawn(&mut self) -> Result<Child, Error>
pub fn spawn(&mut self) -> Result<Child, Error>
Executes the command as a child process, returning a handle to it.
By default, stdin, stdout and stderr are inherited from the parent.
§Examples
Basic usage:
use std::process::Command;
Command::new("ls")
.spawn()
.expect("ls command failed to start");
1.0.0 · sourcepub fn output(&mut self) -> Result<Output, Error>
pub fn output(&mut self) -> Result<Output, Error>
Executes the command as a child process, waiting for it to finish and collecting all of its output.
By default, stdout and stderr are captured (and used to provide the resulting output). Stdin is not inherited from the parent and any attempt by the child process to read from the stdin stream will result in the stream immediately closing.
§Examples
use std::process::Command;
use std::io::{self, Write};
let output = Command::new("/bin/cat")
.arg("file.txt")
.output()
.expect("failed to execute process");
println!("status: {}", output.status);
io::stdout().write_all(&output.stdout).unwrap();
io::stderr().write_all(&output.stderr).unwrap();
assert!(output.status.success());
1.0.0 · sourcepub fn status(&mut self) -> Result<ExitStatus, Error>
pub fn status(&mut self) -> Result<ExitStatus, Error>
Executes a command as a child process, waiting for it to finish and collecting its status.
By default, stdin, stdout and stderr are inherited from the parent.
§Examples
use std::process::Command;
let status = Command::new("/bin/cat")
.arg("file.txt")
.status()
.expect("failed to execute process");
println!("process finished with: {status}");
assert!(status.success());
1.57.0 · sourcepub fn get_program(&self) -> &OsStr
pub fn get_program(&self) -> &OsStr
Returns the path to the program that was given to Command::new
.
§Examples
use std::process::Command;
let cmd = Command::new("echo");
assert_eq!(cmd.get_program(), "echo");
1.57.0 · sourcepub fn get_args(&self) -> CommandArgs<'_>
pub fn get_args(&self) -> CommandArgs<'_>
Returns an iterator of the arguments that will be passed to the program.
This does not include the path to the program as the first argument;
it only includes the arguments specified with Command::arg
and
Command::args
.
§Examples
use std::ffi::OsStr;
use std::process::Command;
let mut cmd = Command::new("echo");
cmd.arg("first").arg("second");
let args: Vec<&OsStr> = cmd.get_args().collect();
assert_eq!(args, &["first", "second"]);
1.57.0 · sourcepub fn get_envs(&self) -> CommandEnvs<'_>
pub fn get_envs(&self) -> CommandEnvs<'_>
Returns an iterator of the environment variables explicitly set for the child process.
Environment variables explicitly set using Command::env
, Command::envs
, and
Command::env_remove
can be retrieved with this method.
Note that this output does not include environment variables inherited from the parent process.
Each element is a tuple key/value pair (&OsStr, Option<&OsStr>)
. A None
value
indicates its key was explicitly removed via Command::env_remove
. The associated key for
the None
value will no longer inherit from its parent process.
An empty iterator can indicate that no explicit mappings were added or that
Command::env_clear
was called. After calling Command::env_clear
, the child process
will not inherit any environment variables from its parent process.
§Examples
use std::ffi::OsStr;
use std::process::Command;
let mut cmd = Command::new("ls");
cmd.env("TERM", "dumb").env_remove("TZ");
let envs: Vec<(&OsStr, Option<&OsStr>)> = cmd.get_envs().collect();
assert_eq!(envs, &[
(OsStr::new("TERM"), Some(OsStr::new("dumb"))),
(OsStr::new("TZ"), None)
]);
1.57.0 · sourcepub fn get_current_dir(&self) -> Option<&Path>
pub fn get_current_dir(&self) -> Option<&Path>
Returns the working directory for the child process.
This returns None
if the working directory will not be changed.
§Examples
use std::path::Path;
use std::process::Command;
let mut cmd = Command::new("ls");
assert_eq!(cmd.get_current_dir(), None);
cmd.current_dir("/bin");
assert_eq!(cmd.get_current_dir(), Some(Path::new("/bin")));