Skip to content

Commit 2622646

Browse files
committed
fs: honor encoding option in glob APIs
Align glob, globSync, and fsPromises.glob with encoding semantics. When encoding is 'buffer', return Buffer paths and Buffer dirent names. Add regression tests and documentation updates to lock behavior.
1 parent 4d0cb65 commit 2622646

File tree

3 files changed

+350
-58
lines changed

3 files changed

+350
-58
lines changed

doc/api/fs.md

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1086,6 +1086,8 @@ behavior is similar to `cp dir1/ dir2/`.
10861086
<!-- YAML
10871087
added: v22.0.0
10881088
changes:
1089+
- version: v26.0.0
1090+
description: Add support for `encoding` as an option.
10891091
- version:
10901092
- v24.1.0
10911093
- v22.17.0
@@ -1115,10 +1117,14 @@ changes:
11151117
If a string array is provided, each string should be a glob pattern that
11161118
specifies paths to exclude. Note: Negation patterns (e.g., '!foo.js') are
11171119
not supported.
1120+
* `encoding` {string} The path encoding. If set to `'buffer'`, the iterator
1121+
yields `Buffer` paths (or `Dirent` entries with `Buffer` names when
1122+
`withFileTypes` is `true`). **Default:** `'utf8'`.
11181123
* `withFileTypes` {boolean} `true` if the glob should return paths as Dirents,
11191124
`false` otherwise. **Default:** `false`.
1120-
* Returns: {AsyncIterator} An AsyncIterator that yields the paths of files
1121-
that match the pattern.
1125+
* Returns: {AsyncIterator} An AsyncIterator that yields matching paths as
1126+
{string} values, or {Buffer} values if `encoding` is `'buffer'` (or
1127+
{fs.Dirent} values when `withFileTypes` is `true`).
11221128
11231129
```mjs
11241130
import { glob } from 'node:fs/promises';
@@ -3195,6 +3201,8 @@ descriptor. See [`fs.utimes()`][].
31953201
<!-- YAML
31963202
added: v22.0.0
31973203
changes:
3204+
- version: v26.0.0
3205+
description: Add support for `encoding` as an option.
31983206
- version:
31993207
- v24.1.0
32003208
- v22.17.0
@@ -3222,11 +3230,15 @@ changes:
32223230
* `exclude` {Function|string\[]} Function to filter out files/directories or a
32233231
list of glob patterns to be excluded. If a function is provided, return
32243232
`true` to exclude the item, `false` to include it. **Default:** `undefined`.
3233+
* `encoding` {string} The path encoding. If set to `'buffer'`, `matches`
3234+
contains `Buffer` paths (or `Dirent` entries with `Buffer` names when
3235+
`withFileTypes` is `true`). **Default:** `'utf8'`.
32253236
* `withFileTypes` {boolean} `true` if the glob should return paths as Dirents,
32263237
`false` otherwise. **Default:** `false`.
32273238
32283239
* `callback` {Function}
32293240
* `err` {Error}
3241+
* `matches` {string\[]|Buffer\[]|fs.Dirent\[]}
32303242
32313243
* Retrieves the files matching the specified pattern.
32323244
@@ -5760,6 +5772,8 @@ Synchronous version of [`fs.futimes()`][]. Returns `undefined`.
57605772
<!-- YAML
57615773
added: v22.0.0
57625774
changes:
5775+
- version: v26.0.0
5776+
description: Add support for `encoding` as an option.
57635777
- version:
57645778
- v24.1.0
57655779
- v22.17.0
@@ -5786,9 +5800,12 @@ changes:
57865800
* `exclude` {Function|string\[]} Function to filter out files/directories or a
57875801
list of glob patterns to be excluded. If a function is provided, return
57885802
`true` to exclude the item, `false` to include it. **Default:** `undefined`.
5803+
* `encoding` {string} The path encoding. If set to `'buffer'`, returns
5804+
`Buffer` paths (or `Dirent` entries with `Buffer` names when
5805+
`withFileTypes` is `true`). **Default:** `'utf8'`.
57895806
* `withFileTypes` {boolean} `true` if the glob should return paths as Dirents,
57905807
`false` otherwise. **Default:** `false`.
5791-
* Returns: {string\[]} paths of files that match the pattern.
5808+
* Returns: {string\[]|Buffer\[]|fs.Dirent\[]} paths of files that match the pattern.
57925809
57935810
```mjs
57945811
import { globSync } from 'node:fs';

0 commit comments

Comments
 (0)