Constructs a newCommand for launching the program atpathprogram, with the following default configuration:

• No arguments to the program
• Inherit the current process’s environment
• Inherit the current process’s working directory
• Inherit stdin/stdout/stderr forspawn orstatus, but create pipes foroutput

Builder methods are provided to change these defaults andotherwise configure the process.

Ifprogram is not an absolute path, thePATH will be searched inan OS-defined way.

The search path to be used may be controlled by setting thePATH environment variable on the Command,but this has some implementation limitations on Windows(see issue #37519).

§Platform-specific behavior

Note on Windows: For executable files with the .exe extension,it can be omitted when specifying the program for this Command.However, if the file has a different extension,a filename including the extension needs to be provided,otherwise the file won’t be found.

§Examples

usestd::process::Command;Command::new("sh")    .spawn()    .expect("sh command failed to start");

§Caveats

Command::new is only intended to accept the path of the program. If you pass a programpath along with arguments likeCommand::new("ls -l").spawn(), it will try to search forls -l literally. The arguments need to be passed separately, such as viaarg orargs.

usestd::process::Command;Command::new("ls")    .arg("-l")// arg passed separately.spawn()    .expect("ls command failed to start");

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 seeargs.

Note that the argument is not passed through a shell, but givenliterally to the program. This means that shell syntax like quotes,escaped characters, word splitting, glob patterns, variable substitution,etc. have no effect.

§Examples

usestd::process::Command;Command::new("ls")    .arg("-l")    .arg("-a")    .spawn()    .expect("ls command failed to start");

Adds multiple arguments to pass to the program.

To pass a single argument seearg.

Note that the arguments are not passed through a shell, but givenliterally to the program. This means that shell syntax like quotes,escaped characters, word splitting, glob patterns, variable substitution, etc.have no effect.

§Examples

usestd::process::Command;Command::new("ls")    .args(["-l","-a"])    .spawn()    .expect("ls command failed to start");

Inserts or updates an explicit environment variable mapping.

This method allows you to add an environment variable mapping to the spawned process oroverwrite a previously set value. You can useCommand::envs to set multiple environmentvariables simultaneously.

Child processes will inherit environment variables from their parent process by default.Environment variables explicitly set usingCommand::env take precedence over inheritedvariables. You can disable environment variable inheritance entirely usingCommand::env_clear or for a single key usingCommand::env_remove.

Note that environment variable names are case-insensitive (butcase-preserving) on Windows and case-sensitive on all other platforms.

§Examples

usestd::process::Command;Command::new("ls")    .env("PATH","/bin")    .spawn()    .expect("ls command failed to start");

Inserts or updates multiple explicit environment variable mappings.

This method allows you to add multiple environment variable mappings to the spawned processor overwrite previously set values. You can useCommand::env to set a single environmentvariable.

Child processes will inherit environment variables from their parent process by default.Environment variables explicitly set usingCommand::envs take precedence over inheritedvariables. You can disable environment variable inheritance entirely usingCommand::env_clear or for a single key usingCommand::env_remove.

Note that environment variable names are case-insensitive (but case-preserving) on Windowsand case-sensitive on all other platforms.

§Examples

usestd::process::{Command, Stdio};usestd::env;usestd::collections::HashMap;letfiltered_env : HashMap<String, String> =    env::vars().filter(|&(refk,_)|        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");

Removes an explicitly set environment variable and prevents inheriting it from a parentprocess.

This method will remove the explicit value of an environment variable set viaCommand::env orCommand::envs. In addition, it will prevent the spawned childprocess from inheriting that environment variable from its parent process.

After callingCommand::env_remove, the value associated with its key fromCommand::get_envs will beNone.

To clear all explicitly set environment variables and disable all environment variableinheritance, you can useCommand::env_clear.

§Examples

Prevent any inheritedGIT_DIR variable from changing the target of thegit command,while allowing all other variables, likeGIT_AUTHOR_NAME.

usestd::process::Command;Command::new("git")    .arg("commit")    .env_remove("GIT_DIR")    .spawn()?;

Clears all explicitly set environment variables and prevents inheriting any parent processenvironment variables.

This method will remove all explicitly added environment variables set viaCommand::envorCommand::envs. In addition, it will prevent the spawned child process from inheritingany environment variable from its parent process.

After callingCommand::env_clear, the iterator fromCommand::get_envs will beempty.

You can useCommand::env_remove to clear a single mapping.

§Examples

The behavior ofsort is affected byLANG andLC_* environment variables.Clearing the environment makessort‘s behavior independent of the parent processes’ language.

usestd::process::Command;Command::new("sort")    .arg("file.txt")    .env_clear()    .spawn()?;

Sets the working directory for the child process.

§Platform-specific behavior

If the program path is relative (e.g.,"./script.sh"), it’s ambiguouswhether it should be interpreted relative to the parent’s workingdirectory or relative tocurrent_dir. The behavior in this case isplatform specific and unstable, and it’s recommended to usecanonicalize to get an absolute program path instead.

§Examples

usestd::process::Command;Command::new("ls")    .current_dir("/bin")    .spawn()    .expect("ls command failed to start");

Configuration for the child process’s standard input (stdin) handle.

Defaults toinherit when used withspawn orstatus, anddefaults topiped when used withoutput.

§Examples

usestd::process::{Command, Stdio};Command::new("ls")    .stdin(Stdio::null())    .spawn()    .expect("ls command failed to start");

Configuration for the child process’s standard output (stdout) handle.

Defaults toinherit when used withspawn orstatus, anddefaults topiped when used withoutput.

§Examples

usestd::process::{Command, Stdio};Command::new("ls")    .stdout(Stdio::null())    .spawn()    .expect("ls command failed to start");

Configuration for the child process’s standard error (stderr) handle.

Defaults toinherit when used withspawn orstatus, anddefaults topiped when used withoutput.

§Examples

usestd::process::{Command, Stdio};Command::new("ls")    .stderr(Stdio::null())    .spawn()    .expect("ls command failed to start");

Executes the command as a child process, returning a handle to it.

By default, stdin, stdout and stderr are inherited from the parent.

§Examples

usestd::process::Command;Command::new("ls")    .spawn()    .expect("ls command failed to start");

Executes the command as a child process, waiting for it to finish andcollecting all of its output.

By default, stdout and stderr are captured (and used to provide theresulting output). Stdin is not inherited from the parent and anyattempt by the child process to read from the stdin stream will resultin the stream immediately closing.

§Examples

usestd::process::Command;usestd::io::{self, Write};letoutput = Command::new("/bin/cat")    .arg("file.txt")    .output()?;println!("status: {}", output.status);io::stdout().write_all(&output.stdout)?;io::stderr().write_all(&output.stderr)?;assert!(output.status.success());

Executes a command as a child process, waiting for it to finish andcollecting its status.

By default, stdin, stdout and stderr are inherited from the parent.

§Examples

usestd::process::Command;letstatus = Command::new("/bin/cat")    .arg("file.txt")    .status()    .expect("failed to execute process");println!("process finished with: {status}");assert!(status.success());

Returns the path to the program that was given toCommand::new.

§Examples

usestd::process::Command;letcmd = Command::new("echo");assert_eq!(cmd.get_program(),"echo");

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 withCommand::arg andCommand::args.

§Examples

usestd::ffi::OsStr;usestd::process::Command;letmutcmd = Command::new("echo");cmd.arg("first").arg("second");letargs: Vec<&OsStr> = cmd.get_args().collect();assert_eq!(args,&["first","second"]);

Returns an iterator of the environment variables explicitly set for the child process.

Environment variables explicitly set usingCommand::env,Command::envs, andCommand::env_remove can be retrieved with this method.

Note that this output does not include environment variables inherited from the parentprocess.

Each element is a tuple key/value pair(&OsStr, Option<&OsStr>). ANone valueindicates its key was explicitly removed viaCommand::env_remove. The associated key fortheNone value will no longer inherit from its parent process.

An empty iterator can indicate that no explicit mappings were added or thatCommand::env_clear was called. After callingCommand::env_clear, the child processwill not inherit any environment variables from its parent process.

§Examples

usestd::ffi::OsStr;usestd::process::Command;letmutcmd = Command::new("ls");cmd.env("TERM","dumb").env_remove("TZ");letenvs: Vec<(&OsStr,Option<&OsStr>)> = cmd.get_envs().collect();assert_eq!(envs,&[    (OsStr::new("TERM"),Some(OsStr::new("dumb"))),    (OsStr::new("TZ"),None)]);

Returns the working directory for the child process.

This returnsNone if the working directory will not be changed.

§Examples

usestd::path::Path;usestd::process::Command;letmutcmd = Command::new("ls");assert_eq!(cmd.get_current_dir(),None);cmd.current_dir("/bin");assert_eq!(cmd.get_current_dir(),Some(Path::new("/bin")));

Returns whether the environment will be cleared for the child process.

This returnstrue ifCommand::env_clear was called, andfalse otherwise.Whentrue, the child process will not inherit any environment variables fromits parent process.

§Examples

#![feature(command_resolved_envs)]usestd::process::Command;letmutcmd = Command::new("ls");assert_eq!(cmd.get_env_clear(),false);cmd.env_clear();assert_eq!(cmd.get_env_clear(),true);

Format the program and arguments of a Command for display. Anynon-utf8 data is lossily converted using the utf8 replacementcharacter.

The default format approximates a shell invocation of the program along with itsarguments. It does not include most of the other command properties. The output is not guaranteed to work(e.g. due to lack of shell-escaping or differences in path resolution).On some platforms you can usethe alternate syntax to show more fields.

Note that the debug implementation is platform-specific.

Returns the argument unchanged.

CallsU::from(self).

That is, this conversion is whatever the implementation ofFrom<T> for U chooses to do.