rename "exclude" to "ignore" and create alias; closes #3871

Author: boneskull

docs/index.md

@@ -817,7 +817,7 @@ Mocha supports the `err.expected` and `err.actual` properties of any thrown `Ass
 
 <!-- AUTO-GENERATED-CONTENT:START (usage:executable=bin/mocha) -->
 
-```plain
+```text
 
 mocha [spec..]
 
@@ -864,7 +864,7 @@ Configuration
   --package  Path to package.json for config                            [string]
 
 File Handling
-  --exclude                        Ignore file(s) or glob pattern(s)
+  --ignore, --exclude              Ignore file(s) or glob pattern(s)
                                                        [array] [default: (none)]
   --extension, --watch-extensions  File extension(s) to load and/or watch
                                                            [array] [default: js]
@@ -883,7 +883,7 @@ Test Filters
 
 Positional Arguments
   spec  One or more files, directories, or globs to test
-                                                    [array] [default: ["test/"]]
+                                                     [array] [default: ["test"]]
 
 Other Options
   --help, -h     Show usage information & exit                         [boolean]
@@ -1075,9 +1075,9 @@ Specify an explicit path to a [`package.json` file](#configuring-mocha-node-js)
 
 By default, Mocha looks for a `package.json` in the current working directory or nearest ancestor, and will use the first file found (regardless of whether it contains a `mocha` property); to suppress `package.json` lookup, use `--no-package`.
 
-### `--exclude <file/directory/glob>`
+### `--ignore <file|directory|glob>`
 
-Explicitly exclude one or more files, directories or "globs" that would otherwise be loaded.
+Explicitly ignore (exclude) one or more test files, directories or globs (e.g., `some/**/files*`) that would otherwise be loaded.
 
 Files specified using `--file` _are not affected_ by this option.
 
@@ -1093,7 +1093,7 @@ Affects `--watch` behavior.
 
 Specifying `--extension` will _remove_ `.js` as a test file extension; use `--extension js` to re-add it. For example, to load `.mjs` and `.js` test files, you must supply `--extension mjs --extension js`.
 
-### `--file <file/directory/glob>`
+### `--file <file|directory|glob>`
 
 Explicitly _include_ a test file to be loaded before other test files files. Multiple uses of `--file` are allowed, and will be loaded in order given.
 

example/config/.mocharc.yml

@@ -6,8 +6,8 @@ check-leaks: false
 color: true
 delay: false
 diff: true
-exclude:
-  - /path/to/some/excluded/file
+ignore:
+  - /path/to/some/ignored/file
 exit: false # could be expressed as "no-exit: true"
 extension:
   - js

lib/cli/run-helpers.js

@@ -123,14 +123,14 @@ exports.handleRequires = (requires = []) => {
  * @param {Object} [opts] - Options
  * @param {string[]} [opts.extension] - File extensions to use
  * @param {string[]} [opts.spec] - Files, dirs, globs to run
- * @param {string[]} [opts.exclude] - Files, dirs, globs to exclude
+ * @param {string[]} [opts.ignore] - Files, dirs, globs to ignore
  * @param {boolean} [opts.recursive=false] - Find files recursively
  * @param {boolean} [opts.sort=false] - Sort test files
  * @returns {string[]} List of files to test
  * @private
  */
 exports.handleFiles = ({
-  exclude = [],
+  ignore = [],
   extension = [],
   file = [],
   recursive = false,
@@ -157,7 +157,7 @@ exports.handleFiles = ({
         newFiles = [newFiles];
       }
       newFiles = newFiles.filter(fileName =>
-        exclude.every(pattern => !minimatch(fileName, pattern))
+        ignore.every(pattern => !minimatch(fileName, pattern))
       );
     }
 

lib/cli/run-option-metadata.js

@@ -14,7 +14,7 @@
  */
 exports.types = {
   array: [
-    'exclude',
+    'ignore',
     'extension',
     'file',
     'global',
@@ -63,6 +63,7 @@ exports.aliases = {
   global: ['globals'],
   grep: ['g'],
   growl: ['G'],
+  ignore: ['exclude'],
   invert: ['i'],
   'no-colors': ['C'],
   reporter: ['R'],

lib/cli/run.js

@@ -82,7 +82,7 @@ exports.builder = yargs =>
         description: 'Show diff on failure',
         group: GROUPS.OUTPUT
       },
-      exclude: {
+      ignore: {
         defaultDescription: '(none)',
         description: 'Ignore file(s) or glob pattern(s)',
         group: GROUPS.FILES,

…fixtures/options/exclude/fail.fixture.js …/fixtures/options/ignore/fail.fixture.jstest/integration/fixtures/options/exclude/fail.fixture.js renamed to test/integration/fixtures/options/ignore/fail.fixture.js test/integration/fixtures/options/exclude/fail.fixture.js renamed to test/integration/fixtures/options/ignore/fail.fixture.js

@@ -5,7 +5,7 @@ var helpers = require('../helpers');
 var runMochaJSON = helpers.runMochaJSON;
 var resolvePath = helpers.resolveFixturePath;
 
-describe('--exclude', function() {
+describe('--ignore', function() {
   /*
    * Runs mocha in {path} with the given args.
    * Calls handleResult with the result.
@@ -26,11 +26,11 @@ describe('--exclude', function() {
     });
   }
 
-  it('should exclude specific files', function(done) {
-    var fixtures = path.join('options', 'exclude', '*');
+  it('should ignore specific files', function(done) {
+    var fixtures = path.join('options', 'ignore', '*');
     runMochaTest(
       fixtures,
-      ['--exclude', resolvePath(path.join('options', 'exclude', 'fail'))],
+      ['--ignore', resolvePath(path.join('options', 'ignore', 'fail'))],
       function(res) {
         expect(res, 'to have passed')
           .and('to have run test', 'should find this test')
@@ -40,11 +40,11 @@ describe('--exclude', function() {
     );
   });
 
-  it('should exclude globbed files', function(done) {
-    var fixtures = path.join('options', 'exclude', '**', '*');
+  it('should ignore globbed files', function(done) {
+    var fixtures = path.join('options', 'ignore', '**', '*');
     runMochaTest(
       fixtures,
-      ['--exclude', '**/fail.fixture.js'],
+      ['--ignore', '**/fail.fixture.js'],
       function(res) {
         expect(res, 'to have passed')
           .and('not to have pending tests')
@@ -54,15 +54,15 @@ describe('--exclude', function() {
     );
   });
 
-  it('should exclude multiple patterns', function(done) {
-    var fixtures = path.join('options', 'exclude', '**', '*');
+  it('should ignore multiple patterns', function(done) {
+    var fixtures = path.join('options', 'ignore', '**', '*');
     runMochaTest(
       fixtures,
       [
-        '--exclude',
-        resolvePath(path.join('options', 'exclude', 'fail')),
-        '--exclude',
-        resolvePath(path.join('options', 'exclude', 'nested', 'fail'))
+        '--ignore',
+        resolvePath(path.join('options', 'ignore', 'fail')),
+        '--ignore',
+        resolvePath(path.join('options', 'ignore', 'nested', 'fail'))
       ],
       function(res) {
         expect(res, 'to have passed')