Skip to content

doc: document glob pattern syntax for fs.glob #62245

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kovan wants to merge 1 commit into
base: main
Choose a base branch
from
+38 −3
Open

doc: document glob pattern syntax for fs.glob #62245

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 38 additions & 3 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1106,7 +1106,7 @@ changes:
description: Add support for `withFileTypes` as an option.
-->

* `pattern` {string|string\[]}
* `pattern` {string|string\[]} One or more glob patterns to match against.
* `options` {Object}
* `cwd` {string|URL} current working directory. **Default:** `process.cwd()`
* `exclude` {Function|string\[]} Function to filter out files/directories or a
Expand All @@ -1120,6 +1120,28 @@ changes:
* Returns: {AsyncIterator} An AsyncIterator that yields the paths of files
that match the pattern.

Retrieves file paths matching the specified glob `pattern`. The pattern
syntax is based on [`minimatch`][] and supports the following constructs:

| Pattern | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `*` | Matches any number of characters in a single path segment, excluding path separators. |
| `?` | Matches exactly one character, excluding path separators. |
| `[abc]` | Matches any one character inside the brackets. Ranges like `[a-z]` and negation like `[!abc]` or `[^abc]` are supported. |
| `**` | Matches zero or more path segments. When used as a full segment (e.g., `a/**/b`), it traverses directories recursively. |
| `{a,b,c}` | Brace expansion. Matches any of the comma-separated alternatives. Nested braces and numeric ranges like `{1..5}` are supported. |

Pattern matching is case-insensitive on macOS and Windows, and
case-sensitive on Linux. Negation patterns (`!pattern`) and `#` comments
are not supported. To exclude paths, use the `exclude` option instead.

When an array of patterns is provided, a file is included if it matches
any of the patterns.

To check whether a single path matches a glob pattern without traversing the
file system, use [`path.matchesGlob()`][]. The `path.matchesGlob()` method
does not support the `exclude` option.

```mjs
import { glob } from 'node:fs/promises';

Expand All @@ -1136,6 +1158,15 @@ const { glob } = require('node:fs/promises');
})();
```

Collecting all results into an array:

```mjs
import { glob } from 'node:fs/promises';

const files = await Array.fromAsync(glob('**/*.js'));
console.log(files);
```

### `fsPromises.lchmod(path, mode)`

<!-- YAML
Expand Down Expand Up @@ -3219,7 +3250,8 @@ changes:
description: Add support for `withFileTypes` as an option.
-->

* `pattern` {string|string\[]}
* `pattern` {string|string\[]} One or more glob patterns to match against.
See [`fsPromises.glob()`][] for supported pattern syntax.

* `options` {Object}
* `cwd` {string|URL} current working directory. **Default:** `process.cwd()`
Expand Down Expand Up @@ -5788,7 +5820,8 @@ changes:
description: Add support for `withFileTypes` as an option.
-->

* `pattern` {string|string\[]}
* `pattern` {string|string\[]} One or more glob patterns to match against.
See [`fsPromises.glob()`][] for supported pattern syntax.
* `options` {Object}
* `cwd` {string|URL} current working directory. **Default:** `process.cwd()`
* `exclude` {Function|string\[]} Function to filter out files/directories or a
Expand Down Expand Up @@ -8778,6 +8811,7 @@ the file contents.
[`fs.writev()`]: #fswritevfd-buffers-position-callback
[`fsPromises.access()`]: #fspromisesaccesspath-mode
[`fsPromises.copyFile()`]: #fspromisescopyfilesrc-dest-mode
[`fsPromises.glob()`]: #fspromisesglobpattern-options
[`fsPromises.mkdtemp()`]: #fspromisesmkdtempprefix-options
[`fsPromises.open()`]: #fspromisesopenpath-flags-mode
[`fsPromises.opendir()`]: #fspromisesopendirpath-options
Expand All @@ -8787,6 +8821,7 @@ the file contents.
[`inotify(7)`]: https://man7.org/linux/man-pages/man7/inotify.7.html
[`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
[`minimatch`]: https://github.com/isaacs/minimatch
[`path.matchesGlob()`]: path.md#pathmatchesglobpath-pattern
[`util.promisify()`]: util.md#utilpromisifyoriginal
[bigints]: https://tc39.github.io/proposal-bigint
[caveats]: #caveats
Expand Down
Loading