Docs: Clarify that -c configs merge with .eslintrc.* (fixes #9535)

Users must use --no-eslintrc to prevent `.eslintrc.*` files from being used

docs/developer-guide/nodejs-api.md

@@ -334,7 +334,7 @@ The `CLIEngine` is a constructor, and you can create a new instance by passing i
 * `cache` - Operate only on changed files (default: `false`). Corresponds to `--cache`.
 * `cacheFile` - Name of the file where the cache will be stored (default: `.eslintcache`). Corresponds to `--cache-file`. Deprecated: use `cacheLocation` instead.
 * `cacheLocation` - Name of the file or directory where the cache will be stored (default: `.eslintcache`). Corresponds to `--cache-location`.
-* `configFile` - The configuration file to use (default: null). Corresponds to `-c`.
+* `configFile` - The configuration file to use (default: null). If `useEslintrc` is true or not specified, this configuration will be merged with any configuration defined in `.eslintrc.*` files, with options in this configuration having precedence. Corresponds to `-c`.
 * `cwd` - Path to a directory that should be considered as the current working directory.
 * `envs` - An array of environments to load (default: empty array). Corresponds to `--env`.
 * `extensions` - An array of filename extensions that should be checked for code. The default is an array containing just `".js"`. Corresponds to `--ext`. It is only used in conjunction with directories, not with filenames or glob patterns.

docs/user-guide/command-line-interface.md

@@ -30,10 +30,12 @@ The command line utility has several options. You can view the options by runnin
 eslint [options] file.js [file.js] [dir]
 
 Basic configuration:
-  -c, --config path::String      Use configuration from this file or shareable config
-  --no-eslintrc                  Disable use of configuration from .eslintrc
+  --no-eslintrc                  Disable use of configuration from .eslintrc.*
+  -c, --config path::String      Use this configuration, overriding
+                                 .eslintrc.* config options if present
   --env [String]                 Specify environments
-  --ext [String]                 Specify JavaScript file extensions - default: .js
+  --ext [String]                 Specify JavaScript file extensions - default:
+                                 .js
   --global [String]              Define global variables
   --parser String                Specify the parser to be used
   --parser-options Object        Specify parser options
@@ -45,37 +47,44 @@ Specifying rules and plugins:
 
 Fixing problems:
   --fix                          Automatically fix problems
-  --fix-dry-run                  Automatically fix problems without saving the changes to the file system
+  --fix-dry-run                  Automatically fix problems without saving the
+                                 changes to the file system
 
 Ignoring files:
   --ignore-path path::String     Specify path of ignore file
   --no-ignore                    Disable use of ignore files and patterns
-  --ignore-pattern [String]      Pattern of files to ignore (in addition to those in .eslintignore)
+  --ignore-pattern [String]      Pattern of files to ignore (in addition to
+                                 those in .eslintignore)
 
 Using stdin:
   --stdin                        Lint code provided on <STDIN> - default: false
   --stdin-filename String        Specify filename to process STDIN as
 
 Handling warnings:
   --quiet                        Report errors only - default: false
-  --max-warnings Int             Number of warnings to trigger nonzero exit code - default: -1
+  --max-warnings Int             Number of warnings to trigger nonzero exit
+                                 code - default: -1
 
 Output:
   -o, --output-file path::String  Specify file to write report to
-  -f, --format String            Use a specific output format - default: stylish
+  -f, --format String            Use a specific output format - default:
+                                 stylish
   --color, --no-color            Force enabling/disabling of color
 
 Inline configuration comments:
   --no-inline-config             Prevent comments from changing config or rules
-  --report-unused-disable-directives  Adds reported errors for unused eslint-disable directives
+  --report-unused-disable-directives  Adds reported errors for unused
+                                      eslint-disable directives
 
 Caching:
   --cache                        Only check changed files - default: false
-  --cache-file path::String      Path to the cache file. Deprecated: use --cache-location - default: .eslintcache
+  --cache-file path::String      Path to the cache file. Deprecated: use
+                                 --cache-location - default: .eslintcache
   --cache-location path::String  Path to the cache file or directory
 
 Miscellaneous:
-  --init                         Run config initialization wizard - default: false
+  --init                         Run config initialization wizard - default:
+                                 false
   --debug                        Output debugging information
   -h, --help                     Show help
   -v, --version                  Output the version number
@@ -92,6 +101,14 @@ Example:
 
 ### Basic configuration
 
+#### `--no-eslintrc`
+
+Disables use of configuration from `.eslintrc.*` and `package.json` files.
+
+Example:
+
+    eslint --no-eslintrc file.js
+
 #### `-c`, `--config`
 
 This option allows you to specify an additional configuration file for ESLint (see [Configuring ESLint](configuring) for more).
@@ -110,13 +127,7 @@ Example:
 
 This example directly uses the sharable config `eslint-config-myconfig`.
 
-#### `--no-eslintrc`
-
-Disables use of configuration from `.eslintrc` and `package.json` files.
-
-Example:
-
-    eslint --no-eslintrc file.js
+If `.eslintrc.*` and/or `package.json` files are also used for configuration (i.e., `--no-eslintrc` was not specified), the configurations will be merged. Options from this configuration file have precedence over the options from `.eslintrc.*` and `package.json` files.
 
 #### `--env`
 

docs/user-guide/configuring.md

@@ -3,7 +3,7 @@
 ESLint is designed to be completely configurable, meaning you can turn off every rule and run only with basic syntax validation, or mix and match the bundled rules and your custom rules to make ESLint perfect for your project. There are two primary ways to configure ESLint:
 
 1. **Configuration Comments** - use JavaScript comments to embed configuration information directly into a file.
-1. **Configuration Files** - use a JavaScript, JSON or YAML file to specify configuration information for an entire directory (other than your home directory) and all of its subdirectories. This can be in the form of an [.eslintrc.*](#configuration-file-formats) file or an `eslintConfig` field in a [`package.json`](https://docs.npmjs.com/files/package.json) file, both of which ESLint will look for and read automatically, or you can specify a configuration file on the [command line](command-line-interface).
+1. **Configuration Files** - use a JavaScript, JSON or YAML file to specify configuration information for an entire directory (other than your home directory) and all of its subdirectories. This can be in the form of an [`.eslintrc.*`](#configuration-file-formats) file or an `eslintConfig` field in a [`package.json`](https://docs.npmjs.com/files/package.json) file, both of which ESLint will look for and read automatically, or you can specify a configuration file on the [command line](command-line-interface).
 
     If you have a configuration file in your home directory (generally `~/`), ESLint uses it **only** if ESLint cannot find any other configuration file.
 
@@ -453,11 +453,15 @@ And in YAML:
 
 ## Using Configuration Files
 
-There are two ways to use configuration files. The first is to save the file wherever you would like and pass its location to the CLI using the `-c` option, such as:
+There are two ways to use configuration files.
+
+The first way to use configuration files is via `.eslintrc.*` and `package.json` files. ESLint will automatically look for them in the directory of the file to be linted, and in successive parent directories all the way up to the root directory of the filesystem (unless `root: true` is specified). This option is useful when you want different configurations for different parts of a project or when you want others to be able to use ESLint directly without needing to remember to pass in the configuration file.
+
+The second is to save the file wherever you would like and pass its location to the CLI using the `-c` option, such as:
 
     eslint -c myconfig.json myfiletotest.js
 
-The second way to use configuration files is via `.eslintrc.*` and `package.json` files. ESLint will automatically look for them in the directory of the file to be linted, and in successive parent directories all the way up to the root directory of the filesystem. This option is useful when you want different configurations for different parts of a project or when you want others to be able to use ESLint directly without needing to remember to pass in the configuration file.
+If you are using one configuration file and want ESLint to ignore any `.eslintrc.*` files, make sure to use `--no-eslintrc` along with the `-c` flag.
 
 In each case, the settings in the configuration file override default settings.
 
@@ -548,15 +552,15 @@ The complete configuration hierarchy, from highest precedence to lowest preceden
     1. `/*global*/`
     1. `/*eslint*/`
     1. `/*eslint-env*/`
-2. Command line options:
+1. Command line options:
     1. `--global`
     1. `--rule`
     1. `--env`
     1. `-c`, `--config`
-3. Project-level configuration:
+1. Project-level configuration:
     1. `.eslintrc.*` or `package.json` file in same directory as linted file
     1. Continue searching for `.eslintrc` and `package.json` files in ancestor directories (parent has highest precedence, then grandparent, etc.), up to and including the root directory or until a config with `"root": true` is found.
-    1. In the absence of any configuration from (1) thru (3), fall back to a personal default configuration in  `~/.eslintrc`.
+1. In the absence of any configuration from (1) thru (3), fall back to a personal default configuration in  `~/.eslintrc`.
 
 ## Extending Configuration Files
 

lib/options.js

@@ -26,17 +26,17 @@ module.exports = optionator({
         {
             heading: "Basic configuration"
         },
-        {
-            option: "config",
-            alias: "c",
-            type: "path::String",
-            description: "Use configuration from this file or shareable config"
-        },
         {
             option: "eslintrc",
             type: "Boolean",
             default: "true",
-            description: "Disable use of configuration from .eslintrc"
+            description: "Disable use of configuration from .eslintrc.*"
+        },
+        {
+            option: "config",
+            alias: "c",
+            type: "path::String",
+            description: "Use this configuration, overriding .eslintrc.* config options if present"
         },
         {
             option: "env",