docs: better global ignores instruction (#19297)

tresorama · Tanujkanti4441 · nzakas · web-flow · commit 8a0a5a8851f7 · 2025-01-17T12:31:02.000+01:00
* docs: update configuration-files.md

* docs: update ignore.md

* docs: small rewrite

* docs: rewrite markdown to fix CI errors

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: rewrite markdown to fix CI errors - 2

* docs: swap code language from `ts` to `js`

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: corrected english syntax

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: better text

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: semi-big rewrite

* docs: better text

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: better english syntax

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: better code example

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: better english syntax

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: better english syntax

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: better text

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: better code example

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: better english syntax

Co-authored-by: Nicholas C. Zakas &lt;nicholas@humanwhocodes.com&gt;

* docs: specify that `name` prop do not break global ignore + better english syntaxs

Co-authored-by: Nicholas C. Zakas &lt;nicholas@humanwhocodes.com&gt;

* docs: better english flow

Co-authored-by: Nicholas C. Zakas &lt;nicholas@humanwhocodes.com&gt;

* docs: better english flow

Co-authored-by: Nicholas C. Zakas &lt;nicholas@humanwhocodes.com&gt;

* docs: better text

Co-authored-by: Nicholas C. Zakas &lt;nicholas@humanwhocodes.com&gt;

* docs: better text

Co-authored-by: Nicholas C. Zakas &lt;nicholas@humanwhocodes.com&gt;

* docs: better english syntax

Co-authored-by: Nicholas C. Zakas &lt;nicholas@humanwhocodes.com&gt;

* 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 &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;

* docs: rewrite tip in `ignore` page

* docs: rename `Ignore Files` page to `Global Ignores` (`ignore.md` md file)

---------

Co-authored-by: Tanuj Kanti &lt;86398394+Tanujkanti4441@users.noreply.github.com&gt;
Co-authored-by: Nicholas C. Zakas &lt;nicholas@humanwhocodes.com&gt;
diff --git a/docs/src/use/configure/configuration-files.md b/docs/src/use/configure/configuration-files.md
@@ -64,7 +64,7 @@ Each configuration object contains all of the information ESLint needs to execut
 
 * `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))
 * `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.
-* `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).
+* `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.
 * `languageOptions` - An object containing settings related to how JavaScript is configured for linting.
     * `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"`)
     * `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
 
 #### Globally ignoring files with `ignores`
 
-If `ignores` is used without any other keys in the configuration object, then the patterns act as global ignores. Here's an example:
+Depending on how the `ignores` property is used, it can behave as non-global `ignores` or as global `ignores`.
+
+* 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.
+* 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.
+
+Global and non-global `ignores` have some usage differences:
+
+* patterns in non-global `ignores` only match the files (`dir/filename.js`) or files within directories (`dir/**`)
+* patterns in global `ignores` can match directories (`dir/`) in addition to the patterns that non-global ignores supports.
+
+For all uses of `ignores`:
+
+* The patterns you define are added after the default ESLint patterns, which are `["**/node_modules/", ".git/"]`.
+* 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`.
 
 ```js
 // eslint.config.js
+
+// Example of global ignores
 export default [
     {
-        ignores: [".config/*"]
-    }
+      ignores: [".config/", "dist/", "tsconfig.json"] // acts as global ignores, due to the absence of other properties
+    },
+    { ... }, // ... other configuration object, inherit global ignores
+    { ... }, // ... other configuration object inherit global ignores
 ];
-```
-
-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/"]`.
 
-For more information on configuring rules, see [Ignore Files](ignore).
+// Example of non-global ignores
+export default [
+    {
+      ignores: [".config/**", "dir1/script1.js"],
+      rules: { ... } // the presence of this property dictates non-global ignores
+    },
+    {
+      ignores: ["other-dir/**", "dist/script2.js"],
+      rules: { ... } // the presence of this property dictates non-global ignores
+    },
+];
+```
 
-::: important
-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`.
-:::
+For more information and examples on configuring rules regarding `ignores`, see [Ignore Files](ignore).
 
 #### Cascading Configuration Objects
 
diff --git a/docs/src/use/configure/ignore.md b/docs/src/use/configure/ignore.md
@@ -14,6 +14,9 @@ eleventyNavigation:
 This page explains how to ignore files using the flat config format. For the deprecated eslintrc format, [see the deprecated documentation](ignore-deprecated).
 :::
 
+::: tip
+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).
+:::
 You can configure ESLint to ignore certain files and directories while linting by specifying one or more glob patterns in the following ways:
 
 * Inside of your `eslint.config.js` file.
