Skip to content

Commit 8a0a5a8

Browse files
tresoramaTanujkanti4441nzakas
authored
docs: better global ignores instruction (#19297)
* docs: update configuration-files.md * docs: update ignore.md * docs: small rewrite * docs: rewrite markdown to fix CI errors Co-authored-by: Tanuj Kanti <[email protected]> * docs: rewrite markdown to fix CI errors - 2 * docs: swap code language from `ts` to `js` Co-authored-by: Tanuj Kanti <[email protected]> * docs: corrected english syntax Co-authored-by: Tanuj Kanti <[email protected]> * docs: better text Co-authored-by: Tanuj Kanti <[email protected]> * docs: semi-big rewrite * docs: better text Co-authored-by: Tanuj Kanti <[email protected]> * docs: better english syntax Co-authored-by: Tanuj Kanti <[email protected]> * docs: better code example Co-authored-by: Tanuj Kanti <[email protected]> * docs: better english syntax Co-authored-by: Tanuj Kanti <[email protected]> * docs: better english syntax Co-authored-by: Tanuj Kanti <[email protected]> * docs: better text Co-authored-by: Tanuj Kanti <[email protected]> * docs: better code example Co-authored-by: Tanuj Kanti <[email protected]> * docs: better english syntax Co-authored-by: Nicholas C. Zakas <[email protected]> * docs: specify that `name` prop do not break global ignore + better english syntaxs Co-authored-by: Nicholas C. Zakas <[email protected]> * docs: better english flow Co-authored-by: Nicholas C. Zakas <[email protected]> * docs: better english flow Co-authored-by: Nicholas C. Zakas <[email protected]> * docs: better text Co-authored-by: Nicholas C. Zakas <[email protected]> * docs: better text Co-authored-by: Nicholas C. Zakas <[email protected]> * docs: better english syntax Co-authored-by: Nicholas C. Zakas <[email protected]> * docs: revert/discard all `ignore.md` changes * docs: add link in `ignore` page that redirect to global vs non-global usage of `ignores` property * docs: now link inside `tip` points to a fragment (hash symbol) of the dest page * docs: better english flow Co-authored-by: Tanuj Kanti <[email protected]> * docs: rewrite tip in `ignore` page * docs: rename `Ignore Files` page to `Global Ignores` (`ignore.md` md file) --------- Co-authored-by: Tanuj Kanti <[email protected]> Co-authored-by: Nicholas C. Zakas <[email protected]>
1 parent 2089707 commit 8a0a5a8

File tree

2 files changed

+37
-11
lines changed

2 files changed

+37
-11
lines changed

‎docs/src/use/configure/configuration-files.md

+34-11
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ Each configuration object contains all of the information ESLint needs to execut
6464

6565
* `name` - A name for the configuration object. This is used in error messages and config inspector to help identify which configuration object is being used. ([Naming Convention](#configuration-naming-conventions))
6666
* `files` - An array of glob patterns indicating the files that the configuration object should apply to. If not specified, the configuration object applies to all files matched by any other configuration object.
67-
* `ignores` - An array of glob patterns indicating the files that the configuration object should not apply to. If not specified, the configuration object applies to all files matched by `files`. If `ignores` is used without any other keys in the configuration object, then the patterns act as [global ignores](#globally-ignoring-files-with-ignores).
67+
* `ignores` - An array of glob patterns indicating the files that the configuration object should not apply to. If not specified, the configuration object applies to all files matched by `files`. If `ignores` is used without any other keys in the configuration object, then the patterns act as [global ignores](#globally-ignoring-files-with-ignores) and it gets applied to every configuration object.
6868
* `languageOptions` - An object containing settings related to how JavaScript is configured for linting.
6969
* `ecmaVersion` - The version of ECMAScript to support. May be any year (i.e., `2022`) or version (i.e., `5`). Set to `"latest"` for the most recent supported version. (default: `"latest"`)
7070
* `sourceType` - The type of JavaScript source code. Possible values are `"script"` for traditional script files, `"module"` for ECMAScript modules (ESM), and `"commonjs"` for CommonJS files. (default: `"module"` for `.js` and `.mjs` files; `"commonjs"` for `.cjs` files)
@@ -212,24 +212,47 @@ Filenames starting with a dot, such as `.gitignore`, are considered to have only
212212

213213
#### Globally ignoring files with `ignores`
214214

215-
If `ignores` is used without any other keys in the configuration object, then the patterns act as global ignores. Here's an example:
215+
Depending on how the `ignores` property is used, it can behave as non-global `ignores` or as global `ignores`.
216+
217+
* When `ignores` is used without any other keys (besides `name`) in the configuration object, then the patterns act as global ignores. This means they apply to every configuration object (not only to the configuration object in which it is defined). Global `ignores` allows you not to have to copy and keep the `ignores` property synchronized in more than one configuration object.
218+
* If `ignores` is used with other properties in the same configuration object, then the patterns act as non-global ignores. This way `ignores` applies only to the configuration object in which it is defined.
219+
220+
Global and non-global `ignores` have some usage differences:
221+
222+
* patterns in non-global `ignores` only match the files (`dir/filename.js`) or files within directories (`dir/**`)
223+
* patterns in global `ignores` can match directories (`dir/`) in addition to the patterns that non-global ignores supports.
224+
225+
For all uses of `ignores`:
226+
227+
* The patterns you define are added after the default ESLint patterns, which are `["**/node_modules/", ".git/"]`.
228+
* The patterns always match files and directories that begin with a dot, such as `.foo.js` or `.fixtures`, unless those files are explicitly ignored. The only dot directory ignored by default is `.git`.
216229

217230
```js
218231
// eslint.config.js
232+
233+
// Example of global ignores
219234
export default [
220235
{
221-
ignores: [".config/*"]
222-
}
236+
ignores: [".config/", "dist/", "tsconfig.json"] // acts as global ignores, due to the absence of other properties
237+
},
238+
{ ... }, // ... other configuration object, inherit global ignores
239+
{ ... }, // ... other configuration object inherit global ignores
223240
];
224-
```
225-
226-
This configuration specifies that all of the files in the `.config` directory should be ignored. This pattern is added after the default patterns, which are `["**/node_modules/", ".git/"]`.
227241

228-
For more information on configuring rules, see [Ignore Files](ignore).
242+
// Example of non-global ignores
243+
export default [
244+
{
245+
ignores: [".config/**", "dir1/script1.js"],
246+
rules: { ... } // the presence of this property dictates non-global ignores
247+
},
248+
{
249+
ignores: ["other-dir/**", "dist/script2.js"],
250+
rules: { ... } // the presence of this property dictates non-global ignores
251+
},
252+
];
253+
```
229254

230-
::: important
231-
Glob patterns always match files and directories that begin with a dot, such as `.foo.js` or `.fixtures`, unless those files are explicitly ignored. The only dot directory ignored by default is `.git`.
232-
:::
255+
For more information and examples on configuring rules regarding `ignores`, see [Ignore Files](ignore).
233256

234257
#### Cascading Configuration Objects
235258

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

+3
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ eleventyNavigation:
1414
This page explains how to ignore files using the flat config format. For the deprecated eslintrc format, [see the deprecated documentation](ignore-deprecated).
1515
:::
1616

17+
::: tip
18+
This page explains how to use `ignores` property of an ESLint configuration object to globally ignore files and directories (aka global ignores). The `ignores` property can behave as either global or non-global depending on how you use it. For more information on non-global ignores, see [Specifying files and ignores](configuration-files#specifying-files-and-ignores). For more information on the differences between global and non-global ignores, see [Globally ignoring files with `ignores`](configuration-files#globally-ignoring-files-with-ignores).
19+
:::
1720
You can configure ESLint to ignore certain files and directories while linting by specifying one or more glob patterns in the following ways:
1821

1922
* Inside of your `eslint.config.js` file.

0 commit comments

Comments
 (0)