From bc343be6671aeb88610ca9dfda64bc8d5d9b1c51 Mon Sep 17 00:00:00 2001 From: Scott Hardin Date: Tue, 19 Nov 2019 20:28:53 -0800 Subject: [PATCH] Fix: Clarify documentation on implicit ignore behavior (fixes #12348) --- docs/user-guide/configuring.md | 37 ++++++++++++++++++++++++++++++---- 1 file changed, 33 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/configuring.md b/docs/user-guide/configuring.md index 7f880198bf41..b39df23d8d2c 100644 --- a/docs/user-guide/configuring.md +++ b/docs/user-guide/configuring.md @@ -1070,12 +1070,26 @@ Of particular note is that like `.gitignore` files, all paths used as patterns f Please see `.gitignore`'s specification for further examples of valid syntax. -In addition to any patterns in a `.eslintignore` file, ESLint ignores files in `/**/node_modules/*` by default. It can still be added using `!`. +In addition to any patterns in the `.eslintignore` file, ESLint always follows a couple implicit ignore rules even if the `--no-ignore` flag is passed. The implicit rules are as follows: -For example, placing the following `.eslintignore` file in the current working directory will not ignore `node_modules/*` and ignore anything in the `build/` directory except `build/index.js`: +* `node_modules/` as well as `bower_components/` directories are ignored. +* Dotfiles as well as Dotfolders and their contents are ignored. + +There are also some exceptions to these rules: + +* If the path to lint is a glob pattern or directory path and contains a Dotfolder, all Dotfiles and Dotfolders will be linted. This includes subDotfiles and subDotfolders that are buried deeper in the directory structure. + + For example, `eslint .config/` will lint all Dotfolders and Dotfiles in the `.config` directory, including immediate children as well as children that are deeper in the directory structure. + +* If the path to lint is a specific file path and the `--no-ignore` flag has been passed, ESLint will lint the file regardless of the implicit ignore rules. + + For example, `eslint .config/my-config-file.js --no-ignore` will cause `my-config-file.js` to be linted. It should be noted that the same command without the `--no-ignore` line will not lint the `my-config-file.js` file. + +Another example: placing the following `.eslintignore` file in the current working directory will ignore the `.git`, `node_modules`, and `bower_components` directories in the project root and anything in the `build/` directory, except `build/index.js`: ```text -# node_modules/* is ignored by default, but can be added using ! +# All .git/* Dotfiles as well as /node_modules/* and /bower_components/* in the project root are ignored by default +# node_modules/* can be added by using ! !node_modules/* # Ignore built files except build/index.js @@ -1127,13 +1141,28 @@ You'll see this warning: ```text foo.js - 0:0 warning File ignored because of your .eslintignore file. Use --no-ignore to override. + 0:0 warning File ignored because of a matching ignore pattern. Use "--no-ignore" to override. ✖ 1 problem (0 errors, 1 warning) ``` This message occurs because ESLint is unsure if you wanted to actually lint the file or not. As the message indicates, you can use `--no-ignore` to omit using the ignore rules. +Consider another scenario where you may want to run ESLint on a specific Dotfile or Dotfolder, but have forgotten to specifically allow those files in your `.eslintignore` file. You would run something like this: + + eslint .config/foo.js + +You would see this warning: + +```text +.config/foo.js + 0:0 warning File ignored by default. Use a negated ignore pattern (like "--ignore-pattern '!'") to override + +✖ 1 problem (0 errors, 1 warning) +``` + +This messages occurs because normally, this file would be ignored by ESLint's implicit ignore rules (as mentioned above). A negated ignore rule in your `.eslintignore` file would override the implicit rule and reinclude this file for linting. Additionally, in this specific case, `--no-ignore` could be used to lint the file as well. + ## Personal Configuration File (deprecated) ⚠️ **This feature has been deprecated**. This feature will be removed in the 8.0.0 release. If you want to continue to use personal configuration files, please use the [`--config` CLI option](https://eslint.org/docs/user-guide/command-line-interface#-c---config). For more information regarding this decision, please see [RFC 28](https://github.com/eslint/rfcs/pull/28) and [RFC 32](https://github.com/eslint/rfcs/pull/32).