Doc: copying the tree and --copy-vcs

sourcefrog · Dec 8, 2024 · 50203a1 · 50203a1
1 parent 3f22f0e
commit 50203a1
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 6 deletions.
diff --git 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
@@ -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.