From 1f6c3d4a2bd74e3fada35eb029ec9fb6b480e99e Mon Sep 17 00:00:00 2001 From: AndrewFinlay Date: Wed, 20 Mar 2019 04:43:49 +1100 Subject: [PATCH] docs: project root directory and `--cwd` doc (#1032) --- README.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 82b4289c3..32161c14f 100644 --- a/README.md +++ b/README.md @@ -195,6 +195,24 @@ Install custom reporters as a development dependency and you can use the `--repo nyc report --reporter= ``` +## Setting the project root directory + +nyc runs a lot of file system operations relative to the project root directory. +During startup nyc will look for the *default* project root directory. +The *default* project root directory is the first directory found that contains a `package.json` file when searching from the current working directory up. +If nyc fails to find a directory containing a `package.json` file, it will use current working directory. +You can change the project root directory with the `--cwd` option. + +nyc uses the project root directory when: + * looking for source files to cover + * creating globs for include and exclude rules during file selection + * loading custom require hooks from the `require` array + +nyc may create artefact directories within the project root, such as: + * the report directory, `/coverage` + * the cache directory, `/node_modules/.cache/nyc` + * the temp directory, `/.nyc_output` + ## Selecting files for coverage By default, nyc only collects coverage for source files that are visited during a test. @@ -217,7 +235,6 @@ We use the following process to remove files from consideration: 2. Remove any files that are found in the `exclude` array. 3. Restore any exclude negated files that have been excluded in the second step. - ### Using include and exclude arrays If there are paths specified in the `include` array, then the set of covered files will be limited to eligible files found in those paths.