]>
Commit | Line | Data |
---|---|---|
8f9d1d4d DC |
1 | --- |
2 | title: Ignoring Code | |
3 | layout: doc | |
4 | eleventyNavigation: | |
5 | key: ignoring code | |
6 | parent: configuring | |
7 | title: Ignoring Code | |
8 | order: 5 | |
5422a9cc | 9 | |
8f9d1d4d | 10 | --- |
5422a9cc TL |
11 | |
12 | ## `ignorePatterns` in Config Files | |
13 | ||
8f9d1d4d | 14 | 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 [the `.eslintignore` file documentation](./ignoring-code#the-eslintignore-file) to learn more. |
5422a9cc TL |
15 | |
16 | ```json | |
17 | { | |
18 | "ignorePatterns": ["temp.js", "**/vendor/*.js"], | |
19 | "rules": { | |
20 | //... | |
21 | } | |
22 | } | |
23 | ``` | |
24 | ||
25 | * Glob patterns in `ignorePatterns` are relative to the directory that the config file is placed in. | |
26 | * You cannot write `ignorePatterns` property under `overrides` property. | |
27 | * Patterns defined in `.eslintignore` take precedence over the `ignorePatterns` property of config files. | |
28 | ||
29 | 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`. | |
30 | ||
31 | 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`. | |
32 | ||
33 | ## The `.eslintignore` File | |
34 | ||
35 | 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 will omit all JavaScript files: | |
36 | ||
37 | ```text | |
38 | **/*.js | |
39 | ``` | |
40 | ||
41 | 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 will not be used. | |
42 | ||
43 | Globs are matched using [node-ignore](https://github.com/kaelzhang/node-ignore), so a number of features are available: | |
44 | ||
45 | * Lines beginning with `#` are treated as comments and do not affect the ignore patterns. | |
8f9d1d4d | 46 | * 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). |
5422a9cc TL |
47 | * Lines preceded by `!` are negated patterns that re-include a pattern that was ignored by an earlier pattern. |
48 | * Ignore patterns behave according to the `.gitignore` [specification](https://git-scm.com/docs/gitignore). | |
49 | ||
50 | 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. | |
51 | ||
52 | ```text | |
53 | # Valid | |
54 | /root/src/*.js | |
55 | ||
56 | # Invalid | |
57 | \root\src\*.js | |
58 | ``` | |
59 | ||
60 | Please see [`.gitignore`](https://git-scm.com/docs/gitignore)'s specification for further examples of valid syntax. | |
61 | ||
62 | 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: | |
63 | ||
64 | * `node_modules/` is ignored. | |
65 | * dot-files (except for `.eslintrc.*`), as well as dot-folders and their contents, are ignored. | |
66 | ||
67 | There are also some exceptions to these rules: | |
68 | ||
69 | * If the path to lint is a glob pattern or directory path and contains a dot-folder, all dot-files and dot-folders will be linted. This includes dot-files and dot-folders that are buried deeper in the directory structure. | |
70 | ||
71 | For example, `eslint .config/` will 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. | |
72 | ||
73 | * 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. | |
74 | ||
75 | 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. | |
76 | ||
77 | * Allowlist and denylist rules specified via `--ignore-pattern` or `.eslintignore` are prioritized above implicit ignore rules. | |
78 | ||
79 | 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: | |
80 | ||
81 | ```text | |
82 | # Allowlist 'test.js' in the '.build' folder | |
83 | # But do not allow anything else in the '.build' folder to be linted | |
84 | !.build | |
85 | .build/* | |
86 | !.build/test.js | |
87 | ``` | |
88 | ||
89 | The following `--ignore-pattern` is also equivalent: | |
90 | ||
8f9d1d4d DC |
91 | ```shell |
92 | eslint --ignore-pattern '!.build' --ignore-pattern '.build/*' --ignore-pattern '!.build/test.js' parent-folder/ | |
93 | ``` | |
5422a9cc TL |
94 | |
95 | ## Using an Alternate File | |
96 | ||
97 | 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: | |
98 | ||
8f9d1d4d DC |
99 | ```shell |
100 | eslint --ignore-path .jshintignore file.js | |
101 | ``` | |
5422a9cc TL |
102 | |
103 | You can also use your `.gitignore` file: | |
104 | ||
8f9d1d4d DC |
105 | ```shell |
106 | eslint --ignore-path .gitignore file.js | |
107 | ``` | |
5422a9cc TL |
108 | |
109 | Any file that follows the standard ignore file format can be used. Keep in mind that specifying `--ignore-path` means that any existing `.eslintignore` file will not be used. Note that globbing rules in `.eslintignore` follow those of `.gitignore`. | |
110 | ||
111 | ## Using eslintIgnore in package.json | |
112 | ||
113 | If an `.eslintignore` file is not found and an alternate file is not specified, ESLint will look in package.json for an `eslintIgnore` key to check for files to ignore. | |
114 | ||
8f9d1d4d DC |
115 | ```json |
116 | { | |
117 | "name": "mypackage", | |
118 | "version": "0.0.1", | |
119 | "eslintConfig": { | |
120 | "env": { | |
121 | "browser": true, | |
122 | "node": true | |
123 | } | |
124 | }, | |
125 | "eslintIgnore": ["hello.js", "world.js"] | |
126 | } | |
127 | ``` | |
5422a9cc TL |
128 | |
129 | ## Ignored File Warnings | |
130 | ||
131 | When you pass directories to ESLint, files and directories are silently ignored. If you pass a specific file to ESLint, then you will see a warning indicating that the file was skipped. For example, suppose you have an `.eslintignore` file that looks like this: | |
132 | ||
133 | ```text | |
134 | foo.js | |
135 | ``` | |
136 | ||
137 | And then you run: | |
138 | ||
8f9d1d4d DC |
139 | ```shell |
140 | eslint foo.js | |
141 | ``` | |
5422a9cc TL |
142 | |
143 | You'll see this warning: | |
144 | ||
145 | ```text | |
146 | foo.js | |
147 | 0:0 warning File ignored because of a matching ignore pattern. Use "--no-ignore" to override. | |
148 | ||
149 | ✖ 1 problem (0 errors, 1 warning) | |
150 | ``` | |
151 | ||
152 | 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. | |
153 | ||
154 | Consider another scenario where you may 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: | |
155 | ||
8f9d1d4d DC |
156 | ```shell |
157 | eslint .config/foo.js | |
158 | ``` | |
5422a9cc TL |
159 | |
160 | You would see this warning: | |
161 | ||
162 | ```text | |
163 | .config/foo.js | |
164 | 0:0 warning File ignored by default. Use a negated ignore pattern (like "--ignore-pattern '!<relative/path/to/filename>'") to override | |
165 | ||
166 | ✖ 1 problem (0 errors, 1 warning) | |
167 | ``` | |
168 | ||
169 | 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 specific case, `--no-ignore` could be used to lint the file as well. |