From 50203a1105c008564ec7ab93e0b2d9795436b2b3 Mon Sep 17 00:00:00 2001
From: Martin Pool <mbp@sourcefrog.net>
Date: Sun, 8 Dec 2024 08:47:57 -0800
Subject: [PATCH] Doc: copying the tree and --copy-vcs

---
 book/src/SUMMARY.md    |  2 +-
 book/src/build-dirs.md | 22 +++++++++++++++++-----
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index e43e0e25..657cd221 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -17,7 +17,7 @@
   - [Listing and previewing mutations](list.md)
   - [Workspaces and packages](workspaces.md)
   - [Passing options to Cargo](cargo-args.md)
-  - [Build directories](build-dirs.md)
+  - [Copying the tree](build-dirs.md)
   - [Using nextest](nextest.md)
   - [Baseline tests](baseline.md)
   - [Testing in-place](in-place.md)
diff --git a/book/src/build-dirs.md b/book/src/build-dirs.md
index 09e562eb..a69b052b 100644
--- a/book/src/build-dirs.md
+++ b/book/src/build-dirs.md
@@ -1,10 +1,18 @@
-# Build directories
+# Copying the tree
 
-cargo-mutants builds mutated code in a temporary directory, containing a copy of your source tree with each mutant successively applied. With `--jobs`, multiple build directories are used in parallel.
+By default, cargo-mutants copies your tree to a temporary directory before mutating and building it. This behavior is turned of by the [`--in-place`](in_place.md) option, which builds mutated code in the original source directory.
 
-## Build-in ignores
+When the [`--jobs`](parallelism.md) option is used, one build directory is created per job.
 
-Files or directories matching these patterns are not copied:
+Some filters are applied while copying the tree, which can be configured by options.
+
+## Troubleshooting tree copies
+
+If the baseline tests fail in the copied directory it is a good first debugging step to try building with `--in-place`.
+
+## `.git` and other version control directories
+
+By default, files or directories matching these patterns are not copied, because they can be large and typically are not needed to build the source:
 
     .git
     .hg
@@ -13,7 +21,9 @@ Files or directories matching these patterns are not copied:
     _darcs
     .pijul
 
-## gitignore
+If your tree's build or tests require the VCS directory then it can be copied with `--copy-vcs=true` or by setting `copy_vcs = true` in `.cargo/mutants.toml`.
+
+## `.gitignore`
 
 From 23.11.2, by default, cargo-mutants will not copy files that are excluded by gitignore patterns, to make copying faster in large trees.
 
@@ -22,3 +32,5 @@ gitignore filtering is only used within trees containing a `.git` directory.
 The filter, based on the [`ignore` crate](https://docs.rs/ignore/), also respects global git ignore configuration in the home directory, as well as `.gitignore` files within the tree.
 
 This behavior can be turned off with `--gitignore=false`, causing ignored files to be copied.
+
+Rust projects typically configure gitignore to exclude the `target/` directory.