Skip to content

doc: enhance glob pattern documentation in fs.md #58988

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
mag123c wants to merge 1 commit into
base: main
Choose a base branch
from
Open

doc: enhance glob pattern documentation in fs.md #58988

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
105 changes: 98 additions & 7 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1430,7 +1430,7 @@ changes:
description: Add support for `withFileTypes` as an option.
-->

* `pattern` {string|string\[]}
* `pattern` {string|string\[]} The glob pattern(s) 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 @@ -1446,9 +1446,52 @@ changes:
* Returns: {AsyncIterator} An AsyncIterator that yields the paths of files
that match the pattern.

Retrieves the file paths matching the specified pattern(s).

When `followSymlinks` is enabled, detected symbolic link cycles are not
traversed recursively.

#### Pattern Syntax

@avivkeller avivkeller Jul 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we defer to glob(7) or POSIX 2.14?

Rather than maintain this evolving(?) syntax?

@mag123c mag123c Jul 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

*, ?, [abc] and the / + leading-dot rules are all in glob(7) and we match them, so I'll link out instead of listing those here. doc/api/test.md already does that.

The rest isn't covered by either spec, though. **, {a,b}, +(...)/!(...) and [^abc] aren't in POSIX 2.14 or glob(7); they come from the vendored minimatch. POSIX actually says a bracket expression starting with ^ is unspecified. 2.14.3 also requires the result to be "sorted according to the collating sequence in effect in the current locale", and fs.glob() doesn't sort at all, so linking there would imply something we don't guarantee.

So, glob(7) for the basics, one small table for the extensions, and a line saying results aren't sorted. Is that okay?


The glob implementation supports the following pattern syntax:

**Basic Wildcards:**

| Pattern | Description |
| -------------------- | -------------------------------------------------------------- |
| `*` | Matches any number of characters within a single path segment. |
| `?` | Matches exactly one character. |
| `[abc]` | Matches any character in the brackets. |
| `[a-z]` | Matches any character in the range. |
| `[!abc]` or `[^abc]` | Matches any character not in the brackets. |
| `[!a-z]` or `[^a-z]` | Matches any character not in the range. |

**Globstar:**

| Pattern | Description |
| --------- | --------------------------------------------- |
| `**` | Matches zero or more directories recursively. |
| `**/*.js` | Matches all `.js` files in any subdirectory. |

**Brace Expansion:**

| Pattern | Description |
| ----------- | ------------------------------------------------ |
| `{a,b,c}` | Matches any of the comma-separated patterns. |
| `{1..5}` | Matches any number in the range (1, 2, 3, 4, 5). |
| `*.{js,ts}` | Matches files with `.js` or `.ts` extensions. |

**Extended Glob Patterns:**

| Pattern | Description |
| ------------ | ------------------------------------------------ |
| `+(pattern)` | Matches one or more occurrences of the pattern. |
| `*(pattern)` | Matches zero or more occurrences of the pattern. |
| `?(pattern)` | Matches zero or one occurrence of the pattern. |
| `!(pattern)` | Matches anything except the pattern. |

#### Examples

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

Expand All @@ -1465,6 +1508,40 @@ const { glob } = require('node:fs/promises');
})();
```

To collect all results into an array, use `Array.fromAsync`:

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

**Common patterns:**

| Pattern | Description |
| --------------------------------------------------- | ------------------------------------------------ |
| `glob('*.js')` | All `.js` files in the current directory. |
| `glob('**/*.{js,ts}')` | All `.js` and `.ts` files recursively. |
| `glob('src/{components,utils}/**/*.js')` | `.js` files in `src/components` or `src/utils`. |
| `glob('test/**/*.{spec,test}.js')` | Test files ending with `.spec.js` or `.test.js`. |
| `glob('**/*.js', { exclude: ['node_modules/**'] })` | All `.js` files except those in `node_modules`. |
| `glob(['src/**/*.js', 'lib/**/*.js'])` | `.js` files in both `src` and `lib` directories. |

#### Platform Considerations

* **Case sensitivity**: Glob patterns are case-insensitive on Windows and macOS,
case-sensitive on other platforms.
* **Path separators**: Forward slashes (`/`) are used in patterns regardless of
platform; they are automatically converted to the appropriate separator.
* **Returned paths**: Results use platform-specific path separators (`\` on Windows,
`/` on POSIX). Paths are relative to `options.cwd` if provided, otherwise
relative to the current working directory.
* **Symlinks**: Symbolic links to directories are not traversed while expanding
`**` patterns unless `followSymlinks` is `true`.
* **Hidden files**: Files starting with `.` are included in results when explicitly
matched, but not when using `*` or `**` patterns.

[`path.matchesGlob()`][] supports the same basic glob pattern syntax for
in-memory path matching, but does not include the `exclude` option.

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

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

* `pattern` {string|string\[]}

* `pattern` {string|string\[]} The glob pattern(s) 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 @@ -3597,11 +3673,17 @@ changes:
followed while expanding `**` patterns. **Default:** `false`.
* `withFileTypes` {boolean} `true` if the glob should return paths as Dirents,
`false` otherwise. **Default:** `false`.

* `callback` {Function}
* `err` {Error}
* `matches` {string\[]|fs.Dirent\[]} An array of paths or Dirent objects that
match the pattern. String paths use platform-specific separators (`\` on
Windows, `/` on POSIX) and are relative to `options.cwd` if provided,
otherwise relative to the current working directory.

Retrieves the file paths matching the specified pattern(s).

* Retrieves the files matching the specified pattern.
See `fsPromises.glob()` for detailed information about pattern syntax,
examples, and behavior.

When `followSymlinks` is enabled, detected symbolic link cycles are not
traversed recursively.
Expand Down Expand Up @@ -6217,7 +6299,7 @@ changes:
description: Add support for `withFileTypes` as an option.
-->

* `pattern` {string|string\[]}
* `pattern` {string|string\[]} The glob pattern(s) 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 @@ -6227,7 +6309,15 @@ changes:
followed while expanding `**` patterns. **Default:** `false`.
* `withFileTypes` {boolean} `true` if the glob should return paths as Dirents,
`false` otherwise. **Default:** `false`.
* Returns: {string\[]} paths of files that match the pattern.
* Returns: {string\[]|fs.Dirent\[]} An array of paths or Dirent objects that
match the pattern. String paths use platform-specific separators (`\` on
Windows, `/` on POSIX) and are relative to `options.cwd` if provided,
otherwise relative to the current working directory.

Retrieves the file paths matching the specified pattern(s).

See `fsPromises.glob()` for detailed information about pattern syntax,
examples, and behavior.

When `followSymlinks` is enabled, detected symbolic link cycles are not
traversed recursively.
Expand Down Expand Up @@ -9329,6 +9419,7 @@ the file contents.
[`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
[`minimatch`]: https://github.com/isaacs/minimatch
[`node:stream/iter`]: stream_iter.md
[`path.matchesGlob()`]: path.md#pathmatchesglobpath-pattern
[`statfs.bsize`]: #statfsbsize
[`stream/iter pipeTo()`]: stream_iter.md#pipetosource-transforms-writer-options
[`stream/iter pull()`]: stream_iter.md#pullsource-transforms-options
Expand Down
Loading