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

Jump to bottom
Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

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

wants to merge 2 commits into from

Conversation

mag123c
Copy link

@mag123c mag123c commented Jul 8, 2025

This PR improves the documentation for fs.glob, fs.globSync, and fsPromises.glob by adding comprehensive pattern syntax
explanations and practical examples.

In the current docs, the pattern parameter is mentioned but not explained clearly, making it difficult for developers to understand
what glob patterns are supported and how to use them effectively.

The updated docs now include:

  • Detailed pattern syntax section covering basic wildcards (*, ?, [abc]), globstar (**), brace expansion ({a,b,c}), and
    extended glob patterns (+(pattern), !(pattern))
  • Comprehensive examples demonstrating recursive searches, multiple patterns, exclusion patterns, and different use cases
  • Platform considerations explaining case sensitivity, path separators, symlink handling, and hidden file behavior
  • Performance notes covering memory efficiency, internal caching, and optimization tips
  • Improved parameter documentation with clearer descriptions and cross-references between API variants

This change resolves #58981

@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. labels Jul 8, 2025
@mag123c mag123c force-pushed the improve-fs-glob-docs branch from 2bc0ba6 to bc710d9 Compare July 8, 2025 08:17
iamstarkov
iamstarkov reviewed Jul 8, 2025
View reviewed changes
Copy link

@iamstarkov iamstarkov left a comment

Choose a reason for hiding this comment

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

thank you, looks good to me

should it be mentioned for path.matchesGlob(path, pattern) as well?

@iamstarkov iamstarkov mentioned this pull request Jul 8, 2025
Open
@mag123c
Copy link
Author

mag123c commented Jul 8, 2025 •
edited
Loading

I’ve added a note referencing path.matchesGlob() to indicate it uses the same glob pattern syntax.
Let me know if that's sufficient here or if you'd prefer a separate section in path.md for that function instead.

@mag123c
doc(fs): document fs.glob pattern syntax and usage
45a5d32 
Improved the documentation for fs.glob, fs.globSync, and fsPromises.glob
by adding comprehensive information about the `pattern` parameter.

The update includes:
- Detailed explanations of glob syntax: wildcards (*, ?), character sets,
  globstar (**), brace expansion ({a,b,c}), and extended patterns (+(x), !(x))
- Practical usage examples including recursive patterns, exclusions,
  and multiple patterns
- Platform considerations such as case sensitivity, path separators,
  symlink handling, and hidden file behavior
- Performance notes on caching, memory efficiency, and matching strategies
- Improved parameter descriptions and consistent formatting across variants
- Added a reference to `path.matchesGlob()` which supports the same glob pattern
  syntax for in-memory path matching

Fixes: nodejs#58981
@mag123c mag123c force-pushed the improve-fs-glob-docs branch from bc710d9 to 45a5d32 Compare July 8, 2025 13:46
@mizulu
Copy link

mizulu commented Jul 9, 2025

path.matchesGlob() is nice to have, but how do we use this to mimic the exclude rules
which do not strictly exclude by matching (as noted on the PR code comment)

and path.matchesGlob() does not support exclude?

@mag123c
Copy link
Author

mag123c commented Jul 10, 2025 •
edited
Loading

@mizulu
path.matchesGlob() only performs simple pattern matching; the exclude functionality would need to be implemented separately.

@jasnell @lpinca
I’ve updated the comment to clarify that path.matchesGlob() does not support exclude, as this might be confusing to users.
Would you mind taking another look when you have a moment?

@mag123c
doc(fs): clarify path.matchesGlob() exclude limitation
1f9519b 
Clarify that path.matchesGlob() only performs pattern matching,
and does not support the exclude functionality available in
fs.glob methods.

This addresses potential user confusion as noted in code review
feedback.

Refs: nodejs#58988
@mizulu
Copy link

mizulu commented Jul 10, 2025 •
edited
Loading

@mag123c ,
thanks, for the confirmation.

I think path.matchesGlob should be extended to mimic the glob functionality
to allow users to mimic similar pattern matching as glob

so one can for example implement globing on an in memory file system ( list of paths )
following the same rules as the node glob. using the path.matchesGlob

This is out side the scope of this PR

I might open an issue for feature request to improve on that.

edit: #59015

@mag123c mag123c requested review from jasnell and lpinca July 10, 2025 00:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@iamstarkov iamstarkov iamstarkov left review comments

@jasnell jasnell Awaiting requested review from jasnell

@lpinca lpinca Awaiting requested review from lpinca

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

fs.glob is stable as of v24 but lacks any documentation regarding pattern argument
6 participants
@mag123c @mizulu @jasnell @iamstarkov @lpinca @nodejs-github-bot