Repository navigation
fs.glob is stable as of v24 but lacks any documentation regarding pattern argument #58981
Description
Activity
PRs are more than welcomed
PRs are more than welcomed
@juanarbol oh man, I wish I could help
I lack the knowledge of implementation details, so I can't contribute, that's why I've raised the issue in the first place
looks like @mag123c suggested a change #58988
@juanarbol, can you proof read it?
Wanted to mention that #58988 gives the impression that the following should be equivalent:
"a{,/b}"
"a?(/b)"However this is not the case:
path.matchesGlob("a/b", "a{,/b}") // true
path.matchesGlob("a/b", "a?(/b)") // falseDon't know if this is expected, or if at least one of those results is a bug, but the docs in the PR read as if both should return true, because a, /b and the empty pattern are a pattern.
I think this is a bug and the PR is fine in this regard, unless it is well known that pattern excludes path separators and/or the empty pattern in certain positions, but I wanted to check here first before opening a new issue.
This issue has been marked as stale due to 90 days of inactivity.
It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.
The size of this gap is easy to underestimate, so I measured it rather than guessing.
I took 25 glob patterns straight out of real config files and 20 ordinary paths, and asked six matchers the same 500 questions: path.matchesGlob, minimatch, picomatch, micromatch, git check-ignore, and TypeScript's include handling.
19 of the 25 patterns are not read the same way by all six. Node lines up with minimatch, picomatch and micromatch most of the time, and the two rules that separate it from the other two are exactly the ones somebody landing on this issue is trying to find out:
- Dotfiles.
src/**matchessrc/.hidden/file.tsunder git and does not underpath.matchesGlob. The four npm and Node matchers skip dotfiles unless asked; git does not. - Braces.
**/*.{ts,tsx}expands underpath.matchesGloband does not under git, so the same string in a.gitignorematches nothing.
Which suggests a fairly small concrete docs ask, from outside the project: for pattern, say which of *, **, ?, character classes, brace expansion and extglob are supported, whether ** crosses a directory boundary, and whether a leading dot is matched by default. Those four questions are what people actually hit when they move a pattern out of a config file and into fs.glob, and right now the only way to answer them is to run it.
I put the harness behind a command so the comparison is reproducible rather than something you have to take my word for: https://www.npmjs.com/package/glob-consensus
Affected URL(s)
https://nodejs.org/docs/latest/api/fs.html#fsglobpattern-options-callback
Description of the problem
Love that native glob support came to node, however fs.glob is stable as of v24 but lacks documentation regarding
patternargument which is confusing, unhelpful and deterring adoption if you come from plethora of user land implementations. For once it prevents me from using it in my cli (edit files by glob patterns), because I can't tell to my cli's users how to write the patterns.I'm looking for documentation for glob's aspects: platform support, performance, supported features.
I'd love to see following popular features mentioned. It will help to know if feature is supported or not, if there any caveats and examples showcasing how feature works.
foo/{1..5}.md,bar/{a,b,c}.js)+(x|y),!(a|b))**,*.js)[[:alpha:][:digit:]])'!a/*.js','*!(b).js')foo-[1-5].js)foo/(abc|xyz).js)Comparison examples with user land libraries like glob, minimatch, micromatch, fast-glob will be helpful too.
Maybe text based matching (without
fsorpathinvolved) can be moved toglobalorutilspackages and documented in depth there?