fs: add ignore option to fs.watch

[mcollina]

Add an ignore option to fs.watch() to filter filesystem events.

Type: string | RegExp | Function | Array<string | RegExp | Function>

fs.watch(dir, { ignore: '*.log' });
fs.watch(dir, { ignore: /\.tmp$/ });
fs.watch(dir, { ignore: (f) => f.startsWith('.') });
fs.watch(dir, { ignore: ['*.log', /\.tmp$/] });

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.86%. Comparing base (637bda0) to head (7571d97).
⚠️ Report is 54 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #61433      +/-   ##
==========================================
+ Coverage   88.51%   89.86%   +1.34%     
==========================================
  Files         704      671      -33     
  Lines      208883   203297    -5586     
  Branches    40334    39098    -1236     
==========================================
- Hits       184890   182684    -2206     
+ Misses      15977    12966    -3011     
+ Partials     8016     7647     -369     

Files with missing lines	Coverage Δ
lib/fs.js	98.19% <100.00%> (+<0.01%)	⬆️
lib/internal/fs/recursive_watch.js	84.91% <100.00%> (+0.54%)	⬆️
lib/internal/fs/watchers.js	87.29% <100.00%> (+2.12%)	⬆️
lib/internal/validators.js	98.25% <100.00%> (+0.09%)	⬆️

... and 95 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/70890/

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @avivkeller.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

[avivkeller]

We have a lazy utility in internal utils

[aduh95]

It looks like there's a consistent failure on macOS

AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:

true !== false

    at process.<anonymous> (/Users/runner/work/node/node/node/test/parallel/test-fs-watch-ignore-recursive.js:165:12)
    at process.emit (node:events:520:22) {
  generatedMessage: true,
  code: 'ERR_ASSERTION',
  actual: true,
  expected: false,
  operator: 'strictEqual',
  diff: 'simple'
}

Node.js v26.0.0-pre
Command: out/Release/node /Users/runner/work/node/node/node/test/parallel/test-fs-watch-ignore-recursive.js

[lpinca]

Can't users already do this by ignoring the events they are not interested in? What are the advantages for having this option in core?

[mcollina]

Can't users already do this by ignoring the events they are not interested in? What are the advantages for having this option in core?

Unfortunately that's not identical. Let's imagine there is a big folder full of files (e.g. node_modules). Watching all those directories and files would create a huge pressure on the OS, because each file watching are data structures kernel-land. There are limits on how many of these a process can create (on some OSes).

It's not equivalent, and it's needded for any pratical application of watch.

[lpinca]

Watching all those directories and files would create a huge pressure on the OS, because each file watching are data structures kernel-land. There are limits on how many of these a process can create (on some OSes).

From a glance, it seems that this PR does not touch the native layer and all the changes are still returned by the OS for later filtering. Am I reading this wrong?

[mcollina]

Watching all those directories and files would create a huge pressure on the OS, because each file watching are data structures kernel-land. There are limits on how many of these a process can create (on some OSes).

From a glance, it seems that this PR does not touch the native layer and all the changes are still returned by the OS for later filtering. Am I reading this wrong?

@lpinca nope, fixed.

[lpinca]

Ok, it makes sense now.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/70967/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/70975/

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/61433
✔  Done loading data for nodejs/node/pull/61433
----------------------------------- PR info ------------------------------------
Title      fs: add ignore option to fs.watch (#61433)
Author     Matteo Collina <matteo.collina@gmail.com> (@mcollina)
Branch     mcollina:fs-watch-ignore-option -> nodejs:main
Labels     fs, semver-minor, notable-change, author ready, needs-ci, lts-watch-v24.x
Commits    8
 - fs: add ignore option to fs.watch
 - doc: add ignore option to fs.watch documentation
 - test: fix flaky test-fs-watch-ignore-recursive
 - test: fix node_modules pattern to match directory events
 - fs: skip watching ignored paths in recursive watcher
 - fs: use getLazy utility for minimatch
 - test: fix flaky test-fs-watch-ignore
 - test: skip fs.watch ignore tests on SunOS
Committers 1
 - Matteo Collina <hello@matteocollina.com>
PR-URL: https://github.com/nodejs/node/pull/61433
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Aviv Keller <me@aviv.sh>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/61433
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Aviv Keller <me@aviv.sh>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Sun, 18 Jan 2026 21:45:54 GMT
   ✔  Approvals: 6
   ✔  - Yagiz Nizipli (@anonrig) (TSC): https://github.com/nodejs/node/pull/61433#pullrequestreview-3675952653
   ✔  - Colin Ihrig (@cjihrig): https://github.com/nodejs/node/pull/61433#pullrequestreview-3678906686
   ✔  - Aviv Keller (@avivkeller): https://github.com/nodejs/node/pull/61433#pullrequestreview-3679859511
   ✔  - Chemi Atlow (@atlowChemi): https://github.com/nodejs/node/pull/61433#pullrequestreview-3691066585
   ✔  - Moshe Atlow (@MoLow): https://github.com/nodejs/node/pull/61433#pullrequestreview-3685541790
   ✔  - Trivikram Kamat (@trivikr): https://github.com/nodejs/node/pull/61433#pullrequestreview-3693330759
   ✔  Last GitHub CI successful
   ℹ  Last Full PR CI on 2026-01-22T21:03:29Z: https://ci.nodejs.org/job/node-test-pull-request/70975/
- Querying data for job/node-test-pull-request/70975/
✔  Build data downloaded
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 61433
From https://github.com/nodejs/node
 * branch                  refs/pull/61433/merge -> FETCH_HEAD
✔  Fetched commits as 34abee5b3bd3..7571d97abe7e
--------------------------------------------------------------------------------
Auto-merging lib/fs.js
[main 3771e0615c] fs: add ignore option to fs.watch
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Sun Jan 18 22:45:27 2026 +0100
 7 files changed, 777 insertions(+), 10 deletions(-)
 create mode 100644 test/parallel/test-fs-watch-ignore-promise.js
 create mode 100644 test/parallel/test-fs-watch-ignore-recursive.js
 create mode 100644 test/parallel/test-fs-watch-ignore.js
[main 7653a97c4d] doc: add ignore option to fs.watch documentation
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Sun Jan 18 22:52:20 2026 +0100
 1 file changed, 9 insertions(+)
[main 29a2817e89] test: fix flaky test-fs-watch-ignore-recursive
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Mon Jan 19 19:18:01 2026 +0100
 1 file changed, 46 insertions(+), 30 deletions(-)
[main b31caaeb6a] test: fix node_modules pattern to match directory events
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Tue Jan 20 13:14:35 2026 +0100
 1 file changed, 3 insertions(+), 1 deletion(-)
[main 48b6a6406b] fs: skip watching ignored paths in recursive watcher
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Tue Jan 20 20:48:46 2026 +0100
 2 files changed, 13 insertions(+), 15 deletions(-)
[main 9126270b52] fs: use getLazy utility for minimatch
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Tue Jan 20 23:25:07 2026 +0100
 1 file changed, 2 insertions(+), 5 deletions(-)
[main 488c940653] test: fix flaky test-fs-watch-ignore
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Wed Jan 21 14:01:51 2026 +0100
 1 file changed, 46 insertions(+), 19 deletions(-)
[main 1e6b3d9ab8] test: skip fs.watch ignore tests on SunOS
 Author: Matteo Collina <hello@matteocollina.com>
 Date: Thu Jan 22 13:10:27 2026 +0100
 3 files changed, 9 insertions(+)
   ✔  Patches applied
There are 8 commits in the PR. Attempting autorebase.
(node:2341) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated.
(Use `node --trace-deprecation ...` to show where the warning was created)
Rebasing (2/16)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
fs: add ignore option to fs.watch
Add an ignore option to fs.watch() to filter filesystem events.

Supports string globs, RegExp, functions, or arrays of these.
PR-URL: #61433

Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>

Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

Reviewed-By: Aviv Keller <me@aviv.sh>

Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
[detached HEAD d92d27d457] fs: add ignore option to fs.watch

Author: Matteo Collina <hello@matteocollina.com>

Date: Sun Jan 18 22:45:27 2026 +0100

7 files changed, 777 insertions(+), 10 deletions(-)

create mode 100644 test/parallel/test-fs-watch-ignore-promise.js

create mode 100644 test/parallel/test-fs-watch-ignore-recursive.js

create mode 100644 test/parallel/test-fs-watch-ignore.js

Rebasing (3/16)

Rebasing (4/16)

Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

doc: add ignore option to fs.watch documentation
PR-URL: #61433

Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>

Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

Reviewed-By: Aviv Keller <me@aviv.sh>

Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
[detached HEAD 322a0af92d] doc: add ignore option to fs.watch documentation

Author: Matteo Collina <hello@matteocollina.com>

Date: Sun Jan 18 22:52:20 2026 +0100

1 file changed, 9 insertions(+)

Rebasing (5/16)

Rebasing (6/16)

Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

test: fix flaky test-fs-watch-ignore-recursive
Use setInterval instead of setTimeout to handle potential event delays

on macOS FSEvents. This ensures that if a write event is missed due to

event coalescing or latency, subsequent writes will eventually trigger

the expected event.
PR-URL: #61433

Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>

Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

Reviewed-By: Aviv Keller <me@aviv.sh>

Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
[detached HEAD eb41ffb52d] test: fix flaky test-fs-watch-ignore-recursive

Author: Matteo Collina <hello@matteocollina.com>

Date: Mon Jan 19 19:18:01 2026 +0100

1 file changed, 46 insertions(+), 30 deletions(-)

Rebasing (7/16)

Rebasing (8/16)

Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

test: fix node_modules pattern to match directory events
On macOS, FSEvents reports events for both directories and files.

The pattern '/node_modules/' only matches files inside node_modules,

not the directory itself. Use an array pattern to match both.
PR-URL: #61433

Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>

Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

Reviewed-By: Aviv Keller <me@aviv.sh>

Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
[detached HEAD 055474096c] test: fix node_modules pattern to match directory events

Author: Matteo Collina <hello@matteocollina.com>

Date: Tue Jan 20 13:14:35 2026 +0100

1 file changed, 3 insertions(+), 1 deletion(-)

Rebasing (9/16)

Rebasing (10/16)

Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

fs: skip watching ignored paths in recursive watcher
Instead of just filtering events, skip watching ignored paths entirely

to avoid kernel resource pressure from unnecessary file watchers.

This is especially important for large directories like node_modules.
PR-URL: #61433

Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>

Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

Reviewed-By: Aviv Keller <me@aviv.sh>

Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
[detached HEAD 088e938fa5] fs: skip watching ignored paths in recursive watcher

Author: Matteo Collina <hello@matteocollina.com>

Date: Tue Jan 20 20:48:46 2026 +0100

2 files changed, 13 insertions(+), 15 deletions(-)

Rebasing (11/16)

Rebasing (12/16)

Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

fs: use getLazy utility for minimatch
PR-URL: #61433

Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>

Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

Reviewed-By: Aviv Keller <me@aviv.sh>

Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
[detached HEAD 42073e5360] fs: use getLazy utility for minimatch

Author: Matteo Collina <hello@matteocollina.com>

Date: Tue Jan 20 23:25:07 2026 +0100

1 file changed, 2 insertions(+), 5 deletions(-)

Rebasing (13/16)

Rebasing (14/16)

Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

test: fix flaky test-fs-watch-ignore
PR-URL: #61433

Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>

Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

Reviewed-By: Aviv Keller <me@aviv.sh>

Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
[detached HEAD 9640f25673] test: fix flaky test-fs-watch-ignore

Author: Matteo Collina <hello@matteocollina.com>

Date: Wed Jan 21 14:01:51 2026 +0100

1 file changed, 46 insertions(+), 19 deletions(-)

Rebasing (15/16)

Rebasing (16/16)

Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

test: skip fs.watch ignore tests on SunOS
PR-URL: #61433

Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>

Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

Reviewed-By: Aviv Keller <me@aviv.sh>

Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Reviewed-By: Moshe Atlow <moshe@atlow.co.il>

Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
[detached HEAD f27d764ebb] test: skip fs.watch ignore tests on SunOS

Author: Matteo Collina <hello@matteocollina.com>

Date: Thu Jan 22 13:10:27 2026 +0100

3 files changed, 9 insertions(+)

Successfully rebased and updated refs/heads/main.
ℹ  Add commit-queue-squash label to land the PR as one commit, or commit-queue-rebase to land as separate commits.

https://github.com/nodejs/node/actions/runs/21266914334

[nodejs-github-bot]

Landed in f700203