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.