docs: Update description of how files are selected for instrumentation

README.md

@@ -195,52 +195,78 @@ Install custom reporters as a development dependency and you can use the `--repo
 nyc report --reporter=<custom-reporter-name>
 ```
 
-## Excluding files
+## Selecting files for coverage
 
-You can tell nyc to exclude specific files and directories by adding
-an `nyc.exclude` array to your `package.json`. Each element of
-the array is a glob pattern indicating which paths should be omitted.
+By default, nyc only collects coverage for source files that are visited
+during a test.  It does this by watching for files that are `require()`'d 
+during the test.  Only source files that are visited during a test will appear 
+in the coverage report and contribute to coverage statistics.  
+
+Nyc will cover all files if the `--all` flag is set.  In this case all files will
+appear in the coverage report and contribute to coverage statistics.
+
+Nyc will only cover files that are located under `cwd`, and then only `*.js` files
+or files with extensions listed in in the `nyc.extension` array.
+
+You can reduce the set of covered files by adding `include` and `exclude` 
+filter arrays to your config.  These allow you to shape the set of covered files 
+by specifying glob patterns that can filter files from  the covered set.  The `exclude` 
+array may also use exclude negated glob patterns, these are specified with 
+a `!` prefix, and can restore sub-paths of excluded paths.
 
 Globs are matched using [minimatch](https://www.npmjs.com/package/minimatch).
 
-For example, the following config will exclude any files with the extension `.spec.js`,
-and anything in the `build` directory:
+We use the following process to remove files from consideration,  
+ * First, limit the set of covered files to those files in paths listed in the 
+   `include` array.  
+ * Then, remove any files that are found in the `exclude` array.
+ * Finally, restore any exclude negated files that have been excluded in the 
+   second step
 
-```json
-{
-  "nyc": {
-    "exclude": [
-      "**/*.spec.js",
-      "build"
-    ]
-  }
-}
-```
-> Note: Since version 9.0 files under `node_modules/` are excluded by default.
-  add the exclude rule `!**/node_modules/` to stop this.
 
-> Note: exclude defaults to `['coverage/**', 'test/**', 'test{,-*}.js', '**/*.test.js', '**/__tests__/**', '**/node_modules/**']`,
+##### 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.
+If the `include` array is left empty then all eligible files will be
+included, equivalent to setting `include` to `['**']`.  Include options
+can be specified on the command line with the `-n` switch.
+
+If there are paths specified in the `exclude` array, then the set of 
+covered files will not feature eligible files found in those paths.
+You can also specify negated paths in the `exclude` array, by prefixing
+them with a `!`.  Negated paths can restore paths that have been 
+already been excluded in the `exclude` array.  Exclude options can be
+specified on the command line with the `-x` switch.
+
+> Note: Exclude defaults to `['coverage/**', 'test/**', 'test{,-*}.js', '**/*.test.js', '**/__tests__/**', '**/node_modules/**']`,
 which would exclude `test`/`__tests__` directories as well as `test.js`, `*.test.js`,
 and `test-*.js` files. Specifying your own exclude property overrides these defaults.
 
-## Including files
+> Note: Since version 9.0, files under `node_modules/` are always excluded by nyc.
+  To reverse this you must add the negated exclude rule `!**/node_modules/`.
+
 
-As an alternative to providing a list of files to `exclude`, you can provide
-an `include` key with a list of globs to specify specific files that should be covered:
+For example, the following config will only collect coverage for files
+in the `src` directory, and exclude any files with the extension
+`.spec.js`.
 
 ```json
 {
   "nyc": {
-    "include": ["**/build/umd/moment.js"]
+    "all": true,
+    "include": [
+      "src/**/*.js"
+    ],
+    "exclude": [
+      "**/*.spec.js"
+    ]
   }
 }
 ```
 
-> `nyc` uses minimatch for glob expansions, you can read its documentation [here](https://www.npmjs.com/package/minimatch).
-
-> Note: include defaults to `['**']`
-
-> ### Use the `--all` flag to include files that have not been required in your tests.
+> Note: Be wary of automatic OS glob expansion when specifying include/exclude globs with the CLI.  
+To prevent this, wrap each glob in single quotes.
 
 ## Require additional modules