eslint/docs/src/use/configure/ignore.md

   1 ---
   2 title: Ignore Files
   3 eleventyNavigation:
   4     key: ignore files
   5     parent: configure
   6     title: Ignore Files
   7     order: 7
   8
   9 ---
  10
  11 You can configure ESLint to ignore certain files and directories while linting by specifying one or more glob patterns.
  12 You can ignore files in the following ways:
  13
  14 * Add `ignorePatterns` to a configuration file.
  15 * Create a dedicated file that contains the ignore patterns (`.eslintignore` by default).
  16
  17 ## `ignorePatterns` in Config Files
  18
  19 You can tell ESLint to ignore specific files and directories using `ignorePatterns` in your config files. `ignorePatterns` patterns follow the same rules as `.eslintignore`. Please see the [`.eslintignore` file documentation](#the-eslintignore-file) to learn more.
  20
  21 ```json
  22 {
  23     "ignorePatterns": ["temp.js", "**/vendor/*.js"],
  24     "rules": {
  25         //...
  26     }
  27 }
  28 ```
  29
  30 * Glob patterns in `ignorePatterns` are relative to the directory that the config file is placed in.
  31 * You cannot write `ignorePatterns` property under `overrides` property.
  32 * Patterns defined in `.eslintignore` take precedence over the `ignorePatterns` property of config files.
  33
  34 If a glob pattern starts with `/`, the pattern is relative to the base directory of the config file. For example, `/foo.js` in `lib/.eslintrc.json` matches to `lib/foo.js` but not `lib/subdir/foo.js`.
  35
  36 If a config is provided via the `--config` CLI option, the ignore patterns that start with `/` in the config are relative to the current working directory rather than the base directory of the given config. For example, if `--config configs/.eslintrc.json` is present, the ignore patterns in the config are relative to `.` rather than `./configs`.
  37
  38 ## The `.eslintignore` File
  39
  40 You can tell ESLint to ignore specific files and directories by creating an `.eslintignore` file in your project's root directory. The `.eslintignore` file is a plain text file where each line is a glob pattern indicating which paths should be omitted from linting. For example, the following omits all JavaScript files:
  41
  42 ```text
  43 **/*.js
  44 ```
  45
  46 When ESLint is run, it looks in the current working directory to find an `.eslintignore` file before determining which files to lint. If this file is found, then those preferences are applied when traversing directories. Only one `.eslintignore` file can be used at a time, so `.eslintignore` files other than the one in the current working directory are not used.
  47
  48 Globs are matched using [node-ignore](https://github.com/kaelzhang/node-ignore), so a number of features are available:
  49
  50 * Lines beginning with `#` are treated as comments and do not affect the ignore patterns.
  51 * Paths are relative to the current working directory. This is also true of paths passed in via the `--ignore-pattern` [command](../command-line-interface#--ignore-pattern).
  52 * Lines preceded by `!` are negated patterns that re-include a pattern that was ignored by an earlier pattern.
  53 * Ignore patterns behave according to the `.gitignore` [specification](https://git-scm.com/docs/gitignore).
  54
  55 Of particular note is that like `.gitignore` files, all paths used as patterns for both `.eslintignore` and `--ignore-pattern` must use forward slashes as their path separators.
  56
  57 ```text
  58 # Valid
  59 /root/src/*.js
  60
  61 # Invalid
  62 \root\src\*.js
  63 ```
  64
  65 Please see [`.gitignore`](https://git-scm.com/docs/gitignore)'s specification for further examples of valid syntax.
  66
  67 In addition to any patterns in the `.eslintignore` file, ESLint always follows a couple of implicit ignore rules even if the `--no-ignore` flag is passed. The implicit rules are as follows:
  68
  69 * `node_modules/` is ignored.
  70 * dot-files (except for `.eslintrc.*`) as well as dot-folders and their contents are ignored.
  71
  72 There are also some exceptions to these rules:
  73
  74 * If the path to lint is a glob pattern or directory path and contains a dot-folder, all dot-files and dot-folders are linted. This includes dot-files and dot-folders that are buried deeper in the directory structure.
  75
  76   For example, `eslint .config/` would lint all dot-folders and dot-files in the `.config` directory, including immediate children as well as children that are deeper in the directory structure.
  77
  78 * If the path to lint is a specific file path and the `--no-ignore` flag has been passed, ESLint would lint the file regardless of the implicit ignore rules.
  79
  80   For example, `eslint .config/my-config-file.js --no-ignore` would cause `my-config-file.js` to be linted. It should be noted that the same command without the `--no-ignore` line would not lint the `my-config-file.js` file.
  81
  82 * Allowlist and denylist rules specified via `--ignore-pattern` or `.eslintignore` are prioritized above implicit ignore rules.
  83
  84   For example, in this scenario, `.build/test.js` is the desired file to allowlist. Because all dot-folders and their children are ignored by default, `.build` must first be allowlisted so that eslint becomes aware of its children. Then, `.build/test.js` must be explicitly allowlisted, while the rest of the content is denylisted. This is done with the following `.eslintignore` file:
  85
  86   ```text
  87   # Allowlist 'test.js' in the '.build' folder
  88   # But do not allow anything else in the '.build' folder to be linted
  89   !.build
  90   .build/*
  91   !.build/test.js
  92   ```
  93
  94   The following `--ignore-pattern` is also equivalent:
  95
  96   ```shell
  97   eslint --ignore-pattern '!.build' --ignore-pattern '.build/*' --ignore-pattern '!.build/test.js' parent-folder/
  98   ```
  99
 100 ## Using an Alternate File
 101
 102 If you'd prefer to use a different file than the `.eslintignore` in the current working directory, you can specify it on the command line using the `--ignore-path` option. For example, you can use `.jshintignore` file because it has the same format:
 103
 104 ```shell
 105 eslint --ignore-path .jshintignore file.js
 106 ```
 107
 108 You can also use your `.gitignore` file:
 109
 110 ```shell
 111 eslint --ignore-path .gitignore file.js
 112 ```
 113
 114 Any file that follows the standard ignore file format can be used. Keep in mind that specifying `--ignore-path` means that the existing `.eslintignore` file is not used. Note that globbing rules in `.eslintignore` follow those of `.gitignore`.
 115
 116 ## Using eslintIgnore in package.json
 117
 118 If an `.eslintignore` file is not found and an alternate file is not specified, ESLint looks in `package.json` for the `eslintIgnore` key to check for files to ignore.
 119
 120 ```json
 121 {
 122     "name": "mypackage",
 123     "version": "0.0.1",
 124     "eslintConfig": {
 125         "env": {
 126             "browser": true,
 127             "node": true
 128         }
 129     },
 130     "eslintIgnore": ["hello.js", "world.js"]
 131 }
 132 ```
 133
 134 ## Ignored File Warnings
 135
 136 When you pass directories to ESLint, files and directories are silently ignored. If you pass a specific file to ESLint, then ESLint creates a warning that the file was skipped. For example, suppose you have an `.eslintignore` file that looks like this:
 137
 138 ```text
 139 foo.js
 140 ```
 141
 142 And then you run:
 143
 144 ```shell
 145 eslint foo.js
 146 ```
 147
 148 You'll see this warning:
 149
 150 ```text
 151 foo.js
 152   0:0  warning  File ignored because of a matching ignore pattern. Use "--no-ignore" to override.
 153
 154 ✖ 1 problem (0 errors, 1 warning)
 155 ```
 156
 157 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.
 158
 159 Consider another scenario where you want to run ESLint on a specific dot-file or dot-folder, but have forgotten to specifically allow those files in your `.eslintignore` file. You would run something like this:
 160
 161 ```shell
 162 eslint .config/foo.js
 163 ```
 164
 165 You would see this warning:
 166
 167 ```text
 168 .config/foo.js
 169   0:0  warning  File ignored by default.  Use a negated ignore pattern (like "--ignore-pattern '!<relative/path/to/filename>'") to override
 170
 171 ✖ 1 problem (0 errors, 1 warning)
 172 ```
 173
 174 This message 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 case, `--no-ignore` could be used to lint the file as well.