Struct Cmd

#[must_use]
pub struct Cmd<'a> { /* private fields */ }

A builder object for constructing a subprocess.

A Cmd is usually created with the [cmd!] macro. The command exists within a context of a Shell and uses its working directory and environment.

Example

use xshell::{Shell, cmd};

let sh = Shell::new()?;

let branch = "main";
let cmd = cmd!(sh, "git switch {branch}").quiet().run()?;
# Ok::<(), xshell::Error>(())

Implementations

impl<'a> Cmd<'a>

fn arg<P: AsRef<OsStr>>(self, arg: P) -> Cmd<'a>

Adds an argument to this commands.

fn args<I>(self, args: I) -> Cmd<'a>
where
    I: IntoIterator,
    I::Item: AsRef<OsStr>,

Adds all of the arguments to this command.

fn env<K: AsRef<OsStr>, V: AsRef<OsStr>>(self, key: K, val: V) -> Cmd<'a>

Overrides the value of the environmental variable for this command.

fn envs<I, K, V>(self, vars: I) -> Cmd<'a>
where
    I: IntoIterator<Item = (K, V)>,
    K: AsRef<OsStr>,
    V: AsRef<OsStr>,

Overrides the values of specified environmental variables for this command.

fn env_remove<K: AsRef<OsStr>>(self, key: K) -> Cmd<'a>

Removes the environment variable from this command.

fn env_clear(self) -> Cmd<'a>

Removes all of the environment variables from this command.

fn ignore_status(self) -> Cmd<'a>

Don't return an error if command the command exits with non-zero status.

By default, non-zero exit status is considered an error.

fn set_ignore_status(&mut self, yes: bool)

Controls whether non-zero exit status is considered an error.

fn quiet(self) -> Cmd<'a>

Don't echo the command itself to stderr.

By default, the command itself will be printed to stderr when executed via Cmd::run.

fn set_quiet(&mut self, yes: bool)

Controls whether the command itself is printed to stderr.

fn secret(self) -> Cmd<'a>

Marks the command as secret.

If a command is secret, it echoes <secret> instead of the program and its arguments, even in error messages.

fn set_secret(&mut self, yes: bool)

Controls whether the command is secret.

fn stdin(self, stdin: impl AsRef<[u8]>) -> Cmd<'a>

Pass the given slice to the standard input of the spawned process.

fn ignore_stdout(self) -> Cmd<'a>

Ignores the standard output stream of the process.

This is equivalent to redirecting stdout to /dev/null. By default, the stdout is inherited or captured.

fn set_ignore_stdout(&mut self, yes: bool)

Controls whether the standard output is ignored.

fn ignore_stderr(self) -> Cmd<'a>

Ignores the standard output stream of the process.

This is equivalent redirecting stderr to /dev/null. By default, the stderr is inherited or captured.

fn set_ignore_stderr(&mut self, yes: bool)

Controls whether the standard error is ignored.

fn run(&self) -> Result<()>

Runs the command.

By default the command itself is echoed to stderr, its standard streams are inherited, and non-zero return code is considered an error. These behaviors can be overridden by using various builder methods of the Cmd.

fn read(&self) -> Result<String>

Run the command and return its stdout as a string. Any trailing newline or carriage return will be trimmed.

fn read_stderr(&self) -> Result<String>

Run the command and return its stderr as a string. Any trailing newline or carriage return will be trimmed.

fn output(&self) -> Result<Output>

Run the command and return its output.

Trait Implementations

impl Display for Cmd<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl<'a> Debug for Cmd<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Auto Trait Implementations

impl<'a> !Send for Cmd<'a>

impl<'a> !Sync for Cmd<'a>

impl<'a> Freeze for Cmd<'a>

impl<'a> RefUnwindSafe for Cmd<'a>

impl<'a> Unpin for Cmd<'a>

impl<'a> UnsafeUnpin for Cmd<'a>

impl<'a> UnwindSafe for Cmd<'a>

Blanket Implementations

impl<T> Any for Cmd<'a> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Cmd<'a> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Cmd<'a> where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> From<T> for Cmd<'a>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToString for Cmd<'a> where T: Display + ?Sized,

fn to_string(&self) -> String

impl<T, U> Into<U> for Cmd<'a> where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for Cmd<'a> where U: Into<T>,

type Error = never;
fn try_from(value: U) -> Result<T, never>

impl<T, U> TryInto<U> for Cmd<'a> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>