Auto merge of rust-lang#53404 - oconnor663:current_dir_behavior, r=alexcrichton

document the platform-specific behavior of Command::current_dir

See also rust-lang#37868.

Here's my initial wording:

> Note that if the program path is relative (e.g. `"./script.sh"`), the interaction between that path and `current_dir` varies across platforms. Windows currently ignores `current_dir` when locating the program, but Unix-like systems interpret the program path relative to `current_dir`. These implementation details aren't considered stable, and it's recommended to call `canonicalize` to get an absolute program path instead of using relative paths and `current_dir` together.

I'd like to get feedback on:

- _Should_ we consider those details stable? It might be disruptive to change them, regardless of what I can get away with claiming in docs :)
- Is `canonicalize` an appropriate recommendation? As discussed in rust-lang#37868 above, there are reasons it's not called automatically in the `Command` implementation.

Author: bors

src/libstd/process.rs

@@ -626,6 +626,14 @@ impl 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:
@@ -638,6 +646,8 @@ impl Command {
     ///         .spawn()
     ///         .expect("ls command failed to start");
     /// ```
+    ///
+    /// [`canonicalize`]: ../fs/fn.canonicalize.html
     #[stable(feature = "process", since = "1.0.0")]
     pub fn current_dir<P: AsRef<Path>>(&mut self, dir: P) -> &mut Command {
         self.inner.cwd(dir.as_ref().as_ref());