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

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]
@@ -1075,9 +1075,9 @@ Specify an explicit path to a [`package.json` file](#configuring-mocha-nodejs) (
 
 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,6 @@ check-leaks: false
 color: true
 delay: false
 diff: true
-exclude:
-  - /path/to/some/excluded/file
 exit: false # could be expressed as "no-exit: true"
 extension:
   - js
@@ -25,6 +23,8 @@ global:
 # fgrep and grep are mutually exclusive
 # grep: something
 growl: false
+ignore:
+  - /path/to/some/ignored/file
 inline-diffs: false
 # needs to be used with grep or fgrep
 # invert: false
@@ -39,8 +39,8 @@ retries: 1
 slow: 75
 sort: false
 spec: test/**/*.spec.js # the positional arguments!
-v8-stack-trace-limit: 100 # V8 flags are prepended with "v8-"
 timeout: false # same as "no-timeout: true" or "timeout: 0"
 trace-warnings: true # node flags ok
 ui: bdd
+v8-stack-trace-limit: 100 # V8 flags are prepended with "v8-"
 watch: false

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,10 +14,10 @@
  */
 exports.types = {
   array: [
-    'exclude',
     'extension',
     'file',
     'global',
+    'ignore',
     'require',
     'reporter-option',
     'spec'
@@ -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,12 +82,6 @@ exports.builder = yargs =>
         description: 'Show diff on failure',
         group: GROUPS.OUTPUT
       },
-      exclude: {
-        defaultDescription: '(none)',
-        description: 'Ignore file(s) or glob pattern(s)',
-        group: GROUPS.FILES,
-        requiresArg: true
-      },
       exit: {
         description: 'Force Mocha to quit after tests complete',
         group: GROUPS.RULES
@@ -143,6 +137,12 @@ exports.builder = yargs =>
         description: 'Enable Growl notifications',
         group: GROUPS.OUTPUT
       },
+      ignore: {
+        defaultDescription: '(none)',
+        description: 'Ignore file(s) or glob pattern(s)',
+        group: GROUPS.FILES,
+        requiresArg: true
+      },
       'inline-diffs': {
         description:
           'Display actual/expected differences inline within each string',

test/integration/fixtures/options/exclude/fail.fixture.js → test/integration/fixtures/options/ignore/fail.fixture.js

@@ -1,6 +1,6 @@
 'use strict';
 
-describe('exclude test fail', function () {
+describe('ignore test fail', function () {
   it('should not run this test', function () {
     throw new Error('should not run');
   });

test/integration/fixtures/options/exclude/nested/fail.fixture.js → test/integration/fixtures/options/ignore/nested/fail.fixture.js

@@ -1,6 +1,6 @@
 'use strict';
 
-describe('exclude test nested fail', function () {
+describe('ignore test nested fail', function () {
   it('should not run this test', function () {
     throw new Error('should not run');
   });

test/integration/fixtures/options/exclude/nested/pass.fixture.js → test/integration/fixtures/options/ignore/nested/pass.fixture.js

@@ -1,5 +1,5 @@
 'use strict';
 
-describe('exclude test nested pass', function () {
+describe('ignore test nested pass', function () {
   it('should find this test', function () {});
 });

test/integration/fixtures/options/exclude/pass.fixture.js → test/integration/fixtures/options/ignore/pass.fixture.js

@@ -1,5 +1,5 @@
 'use strict';
 
-describe('exclude test pass', function () {
+describe('ignore test pass', function () {
   it('should find this test', function () {});
 });

test/integration/options/exclude.spec.js → test/integration/options/ignore.spec.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')