Docs: (flat config) improve global ignores documentation

[bradzacher]

Environment

Node version: v18.16.1
npm version: v9.5.0
Local ESLint version: v8.55.0 (Currently used)
Global ESLint version: Not found
Operating System: darwin 23.1.0

What parser are you using?

Default (Espree)

What did you do?

module.exports = [
  {
    ignores: ["dist"],
  },
  {
    files: ["src/**/*.js"],
    rules: {
      'no-console': 'error',
    }
  },
]

What did you expect to happen?

Given the folder structure:

eslint.config.js
src/not-ignored.js
src/dist/not-ignored.js

I would expect that running eslint src would lint src/not-ignored.js and would skip src/dist/not-ignored.js.

What actually happened?

Both files do get linted

$ ESLINT_USE_FLAT_CONFIG=true node_modules/.bin/eslint src

/Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/dist/ignored.js
  1:1  error  Unexpected console statement  no-console

/Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/not-ignored.js
  1:1  error  Unexpected console statement  no-console

✖ 2 problems (2 errors, 0 warnings)

Link to Minimal Reproducible Example

https://github.com/bradzacher/eslint-flat-config-bugs/tree/main/not-ignored-bug

Participation

• I am willing to submit a pull request for this issue.

Additional comments

probably relevant DEBUG=* output

  @hwc/config-array Anonymous universal config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/not-ignored.js +0ms
  @hwc/config-array Skipped config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/not-ignored.js (based on ignores: **/node_modules/,.git/) +0ms
  @hwc/config-array Matching config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/not-ignored.js +0ms
  @hwc/config-array Skipped config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/not-ignored.js (based on ignores: dist) +0ms
  @hwc/config-array Matching config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/not-ignored.js +1ms
  @hwc/config-array Anonymous universal config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/not-ignored.js +0ms
  eslint:rules Loading rule 'no-console' (remaining=290) +0ms
  @hwc/config-array Anonymous universal config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/dist/ignored.js +5ms
  @hwc/config-array Skipped config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/dist/ignored.js (based on ignores: **/node_modules/,.git/) +0ms
  @hwc/config-array Matching config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/dist/ignored.js +0ms
  @hwc/config-array Skipped config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/dist/ignored.js (based on ignores: dist) +0ms
  @hwc/config-array Matching config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/dist/ignored.js +0ms
  @hwc/config-array Anonymous universal config found for /Users/bjz/temp/eslint-flat-config-bugs/not-ignored-bug/src/dist/ignored.js +0ms

It looks like the src/dist/ignored.js file gets ignored then unignored by the files glob.

This is contrary to what I'd expect based on the docs that state that

If ignores is used without any other keys in the configuration object, then the patterns act as global ignores.

I wouldn't expect that I can implicilty unignore a file by simply adding it to a files - I'd expect that I'd need to explicitly unignore it eg ignores: ['!src/dist/ignored.js']

[bradzacher]

Hmmm. Re-reading the docs a bit more - it looks like the ignores array uses minimatch syntax - not .gitignore syntax like the .eslintignore that I was migrating from.

So the correct form of the ignore is instead **/dist/**.

So this isn't a bug - it's instead (imo) unclear documentation thing.
I was tricked because the example uses "!node_modules/" which looks like gitignore syntax.
It also lists "node_modules/*" with the comment "ignore its content" - but this wouldn't actually match the node module contents properly - it would only ignore any files within node_modules directly (i.e. node_modules/foo/bar.js would not be ignored).

This section probably needs another pass to help clarify the usage.
It would probably also be good to add an example of how one might migrate from a .eslintignore file.

[mdjermanovic]

It also lists "node_modules/*" with the comment "ignore its content" - but this wouldn't actually match the node module contents properly - it would only ignore any files within node_modules directly (i.e. node_modules/foo/bar.js would not be ignored).

In global ignores, patterns match directories too, so node_modules/foo/bar.js is ignored because it's in ignored directory node_modules/foo (the directory is matched by "node_modules/*"). Global ignores work much like .gitignore (matching directories; unignoring) with enhanced syntax and in some cases indeed different semantics in patterns - a notable difference is the one you noticed, dist pattern matches only top-level dist file/directory.

[mdjermanovic]

This section probably needs another pass to help clarify the usage.
It would probably also be good to add an example of how one might migrate from a .eslintignore file.

I also think it would be good to improve this section and migration guide.

[bradzacher]

@mdjermanovic i didn't know there was a migration guide - is it linked from the new config docs? I didn't see it when searching the page.

[nzakas]

Let's hold off until we merge the new docs:

#17840

We already have too many big changes happening to docs and I don't want to have to update them all again.

[nzakas]

Working on this.