Struct Prepare

pub struct Prepare {
    pub command: OsString,
    pub context: Option<Context>,
    pub stdin: Stdio,
    pub stdout: Stdio,
    pub stderr: Stdio,
    pub args: Vec<OsString>,
    pub env: Vec<(OsString, OsString)>,
    pub use_shell: bool,
    pub quote_command: bool,
    pub shell_program: Option<OsString>,
    pub allow_manual_arg_splitting: bool,
}

A structure to keep settings to use when invoking a command via spawn(), after creating it with prepare().

Fields

command: OsString

The command to invoke, either directly or with a shell depending on use_shell.

context: Option<Context>

Additional information to be passed to the spawned command.

stdin: Stdio

The way standard input is configured.

stdout: Stdio

The way standard output is configured.

stderr: Stdio

The way standard error is configured.

args: Vec<OsString>

The arguments to pass to the process being spawned.

env: Vec<(OsString, OsString)>

Environment variables to set for the spawned process.

use_shell: bool

If true, we will use shell_program or sh to execute the command.

quote_command: bool

If true, command is assumed to be a command or path to the program to execute, and it will be shell-quoted to assure it will be executed as is and without splitting across whitespace.

shell_program: Option<OsString>

The name or path to the shell program to use instead of sh.

allow_manual_arg_splitting: bool

If true (default true on Windows and false everywhere else) we will see if it’s safe to manually invoke command after splitting its arguments as a shell would do.

Note that outside of Windows, it’s generally not advisable as this removes support for literal shell scripts with shell-builtins.

This mimics the behaviour we see with git on Windows, which also won’t invoke the shell there at all.

Only effective if use_shell is true as well, as the shell will be used as a fallback if it’s not possible to split arguments as the command-line contains ‘scripting’.

Implementations

impl Prepare

Builder

pub fn command_may_be_shell_script(self) -> Self

If called, the command will be checked for characters that are typical for shell scripts, and if found will use sh to execute it or whatever is set as with_shell_program().

If the command isn’t valid UTF-8, a shell will always be used.

If a shell is used, then arguments given here with arg() or args() will be substituted via "$@" if it’s not already present in the command.

The command_may_be_shell_script_allow_manual_argument_splitting() and command_may_be_shell_script_disallow_manual_argument_splitting() methods also call this method.

If neither this method nor with_shell() is called, commands are always executed verbatim and directly, without the use of a shell.

pub fn with_shell(self) -> Self

If called, unconditionally use a shell to execute the command and its arguments.

This uses sh to execute it, or whatever is set as with_shell_program().

Arguments given here with arg() or args() will be substituted via "$@" if it’s not already present in the command.

If neither this method nor command_may_be_shell_script() is called, commands are always executed verbatim and directly, without the use of a shell. (But see command_may_be_shell_script() on other methods that call that method.)

pub fn with_quoted_command(self) -> Self

Quote the command if it is run in a shell, so its path is left intact.

This is only meaningful if the command has been arranged to run in a shell, either unconditionally with with_shell(), or conditionally with command_may_be_shell_script().

Note that this should not be used if the command is a script - quoting is only the right choice if it’s known to be a program path.

Note also that this does not affect arguments passed with arg() or args(), which do not have to be quoted by the caller because they are passed as "$@" positional parameters ("$1", "$2", and so on).

pub fn with_shell_program(self, program: impl Into<OsString>) -> Self

Set the name or path to the shell program to use if a shell is to be used, to avoid using the default shell which is sh.

Note that that shells that are not Bourne-style cannot be expected to work correctly, because POSIX shell syntax is assumed when searching for and conditionally adding "$@" to receive arguments, where applicable (and in the behaviour of with_quoted_command(), if called).

pub fn without_shell(self) -> Self

Unconditionally turn off using the shell when spawning the command.

Note that not using the shell is the default. So an effective use of this method is some time after command_may_be_shell_script() or with_shell() was called.

pub fn with_context(self, ctx: Context) -> Self

Set additional ctx to be used when spawning the process.

Note that this is a must for most kind of commands that git usually spawns, as at least they need to know the correct Git repository to function.

pub fn command_may_be_shell_script_allow_manual_argument_splitting(self) -> Self

Like command_may_be_shell_script(), but try to split arguments by hand if this can be safely done without a shell.

This is useful on platforms where spawning processes is slow, or where many processes have to be spawned in a row which should be sped up. Manual argument splitting is enabled by default on Windows only.

Note that this does not check for the use of possible shell builtins. Commands may fail or behave differently if they are available as shell builtins and no corresponding external command exists, or the external command behaves differently.

pub fn command_may_be_shell_script_disallow_manual_argument_splitting( self, ) -> Self

Like command_may_be_shell_script(), but don’t allow to bypass the shell even if manual argument splitting can be performed safely.

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

Configure the process to use stdio for stdin.

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

Configure the process to use stdio for stdout.

pub fn stderr(self, stdio: Stdio) -> Self

Configure the process to use stdio for stderr.

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

Add arg to the list of arguments to call the command with.

pub fn args(self, args: impl IntoIterator<Item = impl Into<OsString>>) -> Self

Add args to the list of arguments to call the command with.

pub fn env(self, key: impl Into<OsString>, value: impl Into<OsString>) -> Self

Add key with value to the environment of the spawned command.

impl Prepare

Finalization

pub fn spawn(self) -> Result<Child>

Spawn the command as configured.

Trait Implementations

impl From<Prepare> for Command

fn from(prep: Prepare) -> Command

Converts to this type from the input type.