Rollup merge of rust-lang#123726 - jieyouxu:command-new-docs, r=Nilstrieb

matthiaskrgr · web-flow · commit bdb9aa2f3cdc · 2024-06-13T22:55:44.000+02:00
Clarify `Command::new` behavior for programs with arguments

I mistakenly passed program path along arguments as the same string into `Command::new` a couple of times now. It might be useful to explicitly highlight that `Command::new` intends to accept path to a program, not path to a program plus arguments. Also nudge the user to use `Command::arg` or `Command::args` if they wish to pass arguments.
diff --git a/std/src/process.rs b/std/src/process.rs
@@ -629,6 +629,25 @@ impl Command {
     ///     .spawn()
     ///     .expect("sh command failed to start");
     /// ```
+    ///
+    /// # Caveats
+    ///
+    /// [`Command::new`] is only intended to accept the path of the program. If you pass a program
+    /// path along with arguments like `Command::new("ls -l").spawn()`, it will try to search for
+    /// `ls -l` literally. The arguments need to be passed separately, such as via [`arg`] or
+    /// [`args`].
+    ///
+    /// ```no_run
+    /// use std::process::Command;
+    ///
+    /// Command::new("ls")
+    ///     .arg("-l") // arg passed separately
+    ///     .spawn()
+    ///     .expect("ls command failed to start");
+    /// ```
+    ///
+    /// [`arg`]: Self::arg
+    /// [`args`]: Self::args
     #[stable(feature = "process", since = "1.0.0")]
     pub fn new<S: AsRef<OsStr>>(program: S) -> Command {
         Command { inner: imp::Command::new(program.as_ref()) }
