Document reasoning and report previous error chain

Author: trevyn

crates/cargo-util/src/paths.rs

@@ -413,13 +413,21 @@ fn _create_dir_all(p: &Path) -> Result<()> {
     Ok(())
 }
 
-/// Recursively remove all files and directories at the given directory.
+/// Equivalent to [`std::fs::remove_dir_all`] with better error messages.
 ///
 /// This does *not* follow symlinks.
 pub fn remove_dir_all<P: AsRef<Path>>(p: P) -> Result<()> {
-    _remove_dir_all(p.as_ref()).or_else(|_| {
-        fs::remove_dir_all(p.as_ref())
-            .with_context(|| format!("failed to remove directory `{}`", p.as_ref().display()))
+    _remove_dir_all(p.as_ref()).or_else(|prev_err| {
+        // `std::fs::remove_dir_all` is highly specialized for different platforms
+        // and may be more reliable than a simple walk. We try the walk first in
+        // order to report more detailed errors.
+        fs::remove_dir_all(p.as_ref()).with_context(|| {
+            format!(
+                "failed to remove directory `{}` \n\n---\nPrevious error: {:?}\n---",
+                p.as_ref().display(),
+                prev_err
+            )
+        })
     })
 }
 

src/cargo/ops/cargo_clean.rs

@@ -297,6 +297,7 @@ fn rm_rf(path: &Path, config: &Config, progress: &mut dyn CleaningProgressBar) -
         let entry = entry?;
         progress.on_clean()?;
         if entry.file_type().is_dir() {
+            // `remove_dir_all` is used here due to https://github.com/rust-lang/cargo/issues/11441
             paths::remove_dir_all(entry.path())
                 .with_context(|| "could not remove build directory")?;
         } else {