Skip to content

Commit cf75289

Browse files
committed
doc(fs): clarify glob pattern examples per review feedback
Add note about +(spec|test) pattern matching behavior and provide more precise alternative using brace expansion. Also clarify that returned paths use platform-specific separators. Refs: #58988
1 parent 1f9519b commit cf75289

File tree

1 file changed

+17
-5
lines changed

1 file changed

+17
-5
lines changed

doc/api/fs.md

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1149,6 +1149,11 @@ for await (const entry of glob('src/{components,utils}/**/*.js'))
11491149
// Extended glob patterns
11501150
for await (const entry of glob('test/**/*.+(spec|test).js'))
11511151
console.log(entry); // Test files ending with .spec.js or .test.js
1152+
// Note: This also matches files like 'foo.spectest.js'
1153+
1154+
// More precise pattern using brace expansion
1155+
for await (const entry of glob('test/**/*.{spec,test}.js'))
1156+
console.log(entry); // Only matches .spec.js or .test.js files
11521157
11531158
// Excluding patterns
11541159
for await (const entry of glob('**/*.js', { exclude: ['node_modules/**'] }))
@@ -1174,6 +1179,9 @@ const { glob } = require('node:fs/promises');
11741179
case-sensitive on other platforms
11751180
* **Path separators**: Forward slashes (`/`) are used in patterns regardless of
11761181
platform; they are automatically converted to the appropriate separator
1182+
* **Returned paths**: Results use platform-specific path separators (`\` on Windows,
1183+
`/` on POSIX). Paths are relative to `options.cwd` if provided, otherwise
1184+
relative to the current working directory
11771185
* **Symlinks**: Symbolic links are followed and their targets are included in results
11781186
* **Hidden files**: Files starting with `.` are included in results when explicitly
11791187
matched, but not when using `*` or `**` patterns
@@ -1182,7 +1190,7 @@ const { glob } = require('node:fs/promises');
11821190
11831191
* Results are streamed as an async iterator, allowing for efficient memory usage
11841192
with large result sets
1185-
* The implementation includes internal caching to avoid duplicate filesystem operations
1193+
* The implementation includes internal caching to avoid duplicate file system operations
11861194
* For better performance with large directory trees, consider using more specific
11871195
patterns to reduce the search scope
11881196
@@ -3232,11 +3240,13 @@ changes:
32323240
* `callback` {Function}
32333241
* `err` {Error}
32343242
* `matches` {string\[]|Dirent\[]} An array of paths or Dirent objects that
3235-
match the pattern.
3243+
match the pattern. String paths use platform-specific separators (`\` on
3244+
Windows, `/` on POSIX) and are relative to `options.cwd` if provided,
3245+
otherwise relative to the current working directory.
32363246
32373247
Retrieves the files matching the specified pattern(s).
32383248
3239-
See [`fsPromises.glob()`][] for detailed information about pattern syntax,
3249+
See `fsPromises.glob()` for detailed information about pattern syntax,
32403250
examples, and behavior.
32413251
32423252
```mjs
@@ -5786,11 +5796,13 @@ changes:
57865796
* `withFileTypes` {boolean} `true` if the glob should return paths as Dirents,
57875797
`false` otherwise. **Default:** `false`.
57885798
* Returns: {string\[]|Dirent\[]} An array of paths or Dirent objects that
5789-
match the pattern.
5799+
match the pattern. String paths use platform-specific separators (`\` on
5800+
Windows, `/` on POSIX) and are relative to `options.cwd` if provided,
5801+
otherwise relative to the current working directory.
57905802
57915803
Retrieves the files matching the specified pattern(s).
57925804
5793-
See [`fsPromises.glob()`][] for detailed information about pattern syntax,
5805+
See `fsPromises.glob()` for detailed information about pattern syntax,
57945806
examples, and behavior.
57955807
57965808
```mjs

0 commit comments

Comments
 (0)