basant307/AI_Governance_Project
048
1# Glob2 3Match files using the patterns the shell uses.4 5The most correct and second fastest glob implementation in6JavaScript. (See [**Comparison to Other JavaScript Glob7Implementations**](#comparisons-to-other-fnmatchglob-implementations)8at the bottom of this readme.)9 1012 13## Usage14 15Install with npm16 17```18npm i glob19```20 21> [!NOTE]22> The npm package name is _not_ `node-glob` that's a23> different thing that was abandoned years ago. Just `glob`.24 25```js26// load using import27import { glob, globSync, globStream, globStreamSync, Glob } from 'glob'28// or using commonjs, that's fine, too29const {30 glob,31 globSync,32 globStream,33 globStreamSync,34 Glob,35} = require('glob')36 37// the main glob() and globSync() resolve/return array of filenames38 39// all js files, but don't look in node_modules40const jsfiles = await glob('**/*.js', { ignore: 'node_modules/**' })41 42// pass in a signal to cancel the glob walk43const stopAfter100ms = await glob('**/*.css', {44 signal: AbortSignal.timeout(100),45})46 47// multiple patterns supported as well48const images = await glob(['css/*.{png,jpeg}', 'public/*.{png,jpeg}'])49 50// but of course you can do that with the glob pattern also51// the sync function is the same, just returns a string[] instead52// of Promise<string[]>53const imagesAlt = globSync('{css,public}/*.{png,jpeg}')54 55// you can also stream them, this is a Minipass stream56const filesStream = globStream(['**/*.dat', 'logs/**/*.log'])57 58// construct a Glob object if you wanna do it that way, which59// allows for much faster walks if you have to look in the same60// folder multiple times.61const g = new Glob('**/foo', {})62// glob objects are async iterators, can also do globIterate() or63// g.iterate(), same deal64for await (const file of g) {65 console.log('found a foo file:', file)66}67// pass a glob as the glob options to reuse its settings and caches68const g2 = new Glob('**/bar', g)69// sync iteration works as well70for (const file of g2) {71 console.log('found a bar file:', file)72}73 74// you can also pass withFileTypes: true to get Path objects75// these are like a fs.Dirent, but with some more added powers76// check out https://isaacs.github.io/path-scurry/classes/PathBase.html77// for more info on their API78const g3 = new Glob('**/baz/**', { withFileTypes: true })79g3.stream().on('data', path => {80 console.log(81 'got a path object',82 path.fullpath(),83 path.isDirectory(),84 path.readdirSync().map(e => e.name),85 )86})87 88// if you use stat:true and withFileTypes, you can sort results89// by things like modified time, filter by permission mode, etc.90// All Stats fields will be available in that case. Slightly91// slower, though.92// For example:93const results = await glob('**', { stat: true, withFileTypes: true })94 95const timeSortedFiles = results96 .sort((a, b) => a.mtimeMs - b.mtimeMs)97 .map(path => path.fullpath())98 99const groupReadableFiles = results100 .filter(path => path.mode & 0o040)101 .map(path => path.fullpath())102 103// custom ignores can be done like this, for example by saying104// you'll ignore all markdown files, and all folders named 'docs'105const customIgnoreResults = await glob('**', {106 ignore: {107 ignored: p => /\.md$/.test(p.name),108 childrenIgnored: p => p.isNamed('docs'),109 },110})111 112// another fun use case, only return files with the same name as113// their parent folder, plus either `.ts` or `.js`114const folderNamedModules = await glob('**/*.{ts,js}', {115 ignore: {116 ignored: p => {117 const pp = p.parent118 return !(p.isNamed(pp.name + '.ts') || p.isNamed(pp.name + '.js'))119 },120 },121})122 123// find all files edited in the last hour, to do this, we ignore124// all of them that are more than an hour old125const newFiles = await glob('**', {126 // need stat so we have mtime127 stat: true,128 // only want the files, not the dirs129 nodir: true,130 ignore: {131 ignored: p => {132 return new Date() - p.mtime > 60 * 60 * 1000133 },134 // could add similar childrenIgnored here as well, but135 // directory mtime is inconsistent across platforms, so136 // probably better not to, unless you know the system137 // tracks this reliably.138 },139})140```141 142> [!NOTE]143> Glob patterns should always use `/` as a path separator,144> even on Windows systems, as `\` is used to escape glob145> characters. If you wish to use `\` as a path separator _instead146> of_ using it as an escape character on Windows platforms, you may147> set `windowsPathsNoEscape:true` in the options. In this mode,148> special glob characters cannot be escaped, making it impossible149> to match a literal `*` `?` and so on in filenames.150 151## Command Line Interface152 153The glob CLI has been moved to the `glob-bin` package, and must154be installed separately, as of version 13.155 156```157npm install glob-bin158```159 160## `glob(pattern: string | string[], options?: GlobOptions) => Promise<string[] | Path[]>`161 162Perform an asynchronous glob search for the pattern(s) specified.163Returns164[Path](https://isaacs.github.io/path-scurry/classes/PathBase)165objects if the `withFileTypes` option is set to `true`. See below166for full options field desciptions.167 168## `globSync(pattern: string | string[], options?: GlobOptions) => string[] | Path[]`169 170Synchronous form of `glob()`.171 172Alias: `glob.sync()`173 174## `globIterate(pattern: string | string[], options?: GlobOptions) => AsyncGenerator<string>`175 176Return an async iterator for walking glob pattern matches.177 178Alias: `glob.iterate()`179 180## `globIterateSync(pattern: string | string[], options?: GlobOptions) => Generator<string>`181 182Return a sync iterator for walking glob pattern matches.183 184Alias: `glob.iterate.sync()`, `glob.sync.iterate()`185 186## `globStream(pattern: string | string[], options?: GlobOptions) => Minipass<string | Path>`187 188Return a stream that emits all the strings or `Path` objects and189then emits `end` when completed.190 191Alias: `glob.stream()`192 193## `globStreamSync(pattern: string | string[], options?: GlobOptions) => Minipass<string | Path>`194 195Syncronous form of `globStream()`. Will read all the matches as196fast as you consume them, even all in a single tick if you197consume them immediately, but will still respond to backpressure198if they're not consumed immediately.199 200Alias: `glob.stream.sync()`, `glob.sync.stream()`201 202## `hasMagic(pattern: string | string[], options?: GlobOptions) => boolean`203 204Returns `true` if the provided pattern contains any "magic" glob205characters, given the options provided.206 207Brace expansion is not considered "magic" unless the208`magicalBraces` option is set, as brace expansion just turns one209string into an array of strings. So a pattern like `'x{a,b}y'`210would return `false`, because `'xay'` and `'xby'` both do not211contain any magic glob characters, and it's treated the same as212if you had called it on `['xay', 'xby']`. When213`magicalBraces:true` is in the options, brace expansion _is_214treated as a pattern having magic.215 216## `escape(pattern: string, options?: GlobOptions) => string`217 218Escape all magic characters in a glob pattern, so that it will219only ever match literal strings220 221If the `windowsPathsNoEscape` option is used, then characters are222escaped by wrapping in `[]`, because a magic character wrapped in223a character class can only be satisfied by that exact character.224 225Slashes (and backslashes in `windowsPathsNoEscape` mode) cannot226be escaped or unescaped.227 228## `unescape(pattern: string, options?: GlobOptions) => string`229 230Un-escape a glob string that may contain some escaped characters.231 232If the `windowsPathsNoEscape` option is used, then square-brace233escapes are removed, but not backslash escapes. For example, it234will turn the string `'[*]'` into `*`, but it will not turn235`'\\*'` into `'*'`, because `\` is a path separator in236`windowsPathsNoEscape` mode.237 238When `windowsPathsNoEscape` is not set, then both brace escapes239and backslash escapes are removed.240 241Slashes (and backslashes in `windowsPathsNoEscape` mode) cannot242be escaped or unescaped.243 244## Class `Glob`245 246An object that can perform glob pattern traversals.247 248### `const g = new Glob(pattern: string | string[], options: GlobOptions)`249 250Options object is required.251 252See full options descriptions below.253 254> [!NOTE]255> A previous `Glob` object can be passed as the256> `GlobOptions` to another `Glob` instantiation to re-use settings257> and caches with a new pattern.258 259Traversal functions can be called multiple times to run the walk260again.261 262### `g.stream()`263 264Stream results asynchronously.265 266### `g.streamSync()`267 268Stream results synchronously.269 270### `g.iterate()`271 272Default async iteration function. Returns an AsyncGenerator that273iterates over the results.274 275### `g.iterateSync()`276 277Default sync iteration function. Returns a Generator that278iterates over the results.279 280### `g.walk()`281 282Returns a Promise that resolves to the results array.283 284### `g.walkSync()`285 286Returns a results array.287 288### Properties289 290All options are stored as properties on the `Glob` object.291 292- `opts` The options provided to the constructor.293- `patterns` An array of parsed immutable `Pattern` objects.294 295## Options296 297Exported as `GlobOptions` TypeScript interface. A `GlobOptions`298object may be provided to any of the exported methods, and must299be provided to the `Glob` constructor.300 301All options are optional, boolean, and false by default, unless302otherwise noted.303 304All resolved options are added to the Glob object as properties.305 306If you are running many `glob` operations, you can pass a Glob307object as the `options` argument to a subsequent operation to308share the previously loaded cache.309 310- `cwd` String path or `file://` string or URL object. The311 current working directory in which to search. Defaults to312 `process.cwd()`. See also: "Windows, CWDs, Drive Letters, and313 UNC Paths", below.314 315 This option may be either a string path or a `file://` URL316 object or string.317 318- `root` A string path resolved against the `cwd` option, which319 is used as the starting point for absolute patterns that start320 with `/`, (but not drive letters or UNC paths on Windows).321 322 To start absolute and non-absolute patterns in the same path,323 you can use `{root:''}`. However, be aware that on Windows324 systems, a pattern like `x:/*` or `//host/share/*` will325 _always_ start in the `x:/` or `//host/share` directory,326 regardless of the `root` setting.327 328> [!NOTE] This _doesn't_ necessarily limit the walk to the329> `root` directory, and doesn't affect the cwd starting point330> for non-absolute patterns. A pattern containing `..` will331> still be able to traverse out of the root directory, if it332> is not an actual root directory on the filesystem, and any333> non-absolute patterns will be matched in the `cwd`. For334> example, the pattern `/../*` with `{root:'/some/path'}`335> will return all files in `/some`, not all files in336> `/some/path`. The pattern `*` with `{root:'/some/path'}`337> will return all the entries in the cwd, not the entries in338> `/some/path`.339 340- `windowsPathsNoEscape` Use `\\` as a path separator _only_, and341 _never_ as an escape character. If set, all `\\` characters are342 replaced with `/` in the pattern.343 344> [!NOTE]345> This makes it **impossible** to match against paths346> containing literal glob pattern characters, but allows matching347> with patterns constructed using `path.join()` and348> `path.resolve()` on Windows platforms, mimicking the (buggy!)349> behavior of Glob v7 and before on Windows. Please use with350> caution, and be mindful of [the caveat below about Windows351> paths](#windows). (For legacy reasons, this is also set if352> `allowWindowsEscape` is set to the exact value `false`.)353 354- `dot` Include `.dot` files in normal matches and `globstar`355 matches. Note that an explicit dot in a portion of the pattern356 will always match dot files.357 358- `magicalBraces` Treat brace expansion like `{a,b}` as a "magic"359 pattern. Has no effect if {@link nobrace} is set.360 361 Only has effect on the {@link hasMagic} function, no effect on362 glob pattern matching itself.363 364- `dotRelative` Prepend all relative path strings with `./` (or365 `.\` on Windows).366 367 Without this option, returned relative paths are "bare", so368 instead of returning `'./foo/bar'`, they are returned as369 `'foo/bar'`.370 371 Relative patterns starting with `'../'` are not prepended with372 `./`, even if this option is set.373 374- `mark` Add a `/` character to directory matches. Note that this375 requires additional stat calls.376 377- `nobrace` Do not expand `{a,b}` and `{1..3}` brace sets.378 379- `noglobstar` Do not match `**` against multiple filenames. (Ie,380 treat it as a normal `*` instead.)381 382- `noext` Do not match "extglob" patterns such as `+(a|b)`.383 384- `nocase` Perform a case-insensitive match. This defaults to385 `true` on macOS and Windows systems, and `false` on all others.386 387> [!NOTE]388> `nocase` should only be explicitly set when it is known that389> the filesystem's case sensitivity differs from the platform390> default. If set `true` on case-sensitive file systems, or391> `false` on case-insensitive file systems, then the walk may392> return more or less results than expected.393>394> As a shortcut to avoid excessive `RegExp` creations, `Glob`395> will use string portions as-is to `readdir()` calls while doing396> its traversal. If you are setting a `nocase: true` match on a397> file system that is in fact case sensitive, then this will398> result in matches not being found that you might expect,399> because for example the pattern `Foo/*` will fail to read the400> `FOO/` or `foo/` directories.401>402> On the other hand, if you set `nocase: false` on a403> case-_insensitive_ system, then the opposite problem occurs:404> `Foo/*` will match `foo/bar`, but because we only detect the405> existence of the `foo/` folder by successfully performing a406> `readdir`, there's no way to know what the "real" case is, and407> the match will be reported as `Foo/bar`, using the case of the408> string portion of the glob pattern.409>410> The default is usually correct, however it _is_ possible to411> mount file systems with a different case-sensitivity from the412> host system. If you know this is the case, set this flag413> appropriately to the file system you are searching.414 415- `maxDepth` Specify a number to limit the depth of the directory416 traversal to this many levels below the `cwd`.417 418- `matchBase` Perform a basename-only match if the pattern does419 not contain any slash characters. That is, `*.js` would be420 treated as equivalent to `**/*.js`, matching all js files in421 all directories.422 423- `nodir` Do not match directories, only files. (Note: to match424 _only_ directories, put a `/` at the end of the pattern.)425 426> [!NOTE]427> When `follow` and `nodir` are both set, then symbolic428> links to directories are also omitted.429 430- `stat` Call `lstat()` on all entries, whether required or not431 to determine whether it's a valid match. When used with432 `withFileTypes`, this means that matches will include data such433 as modified time, permissions, and so on. Note that this will434 incur a performance cost due to the added system calls.435 436- `ignore` string or string[], or an object with `ignored` and437 `childrenIgnored` methods.438 439 If a string or string[] is provided, then this is treated as440 a glob pattern or array of glob patterns to exclude from441 matches. To ignore all children within a directory, as well442 as the entry itself, append `'/**'` to the ignore pattern.443 444 If an object is provided that has `ignored(path)` and/or445 `childrenIgnored(path)` methods, then these methods will be446 called to determine whether any Path is a match or if its447 children should be traversed, respectively.448 449 The `path` argument to the methods will be a450 [`path-scurry`](https://isaacs.github.io/path-scurry/index.html)451 [`Path`](https://isaacs.github.io/path-scurry/classes/PathBase)452 object, which extends453 [`fs.Dirent`](https://nodejs.org/docs/latest/api/fs.html#class-fsdirent)454 with additional useful methods like455 [`.fullpath()`](https://isaacs.github.io/path-scurry/classes/PathBase.html#fullpath),456 [`.relative()`](https://isaacs.github.io/path-scurry/classes/PathBase.html#relative),457 and more.458 459> [!NOTE]460> `ignore` patterns are _always_ in `dot:true` mode,461> regardless of any other settings.462 463- `follow` Follow symlinked directories when expanding `**`464 patterns. This can result in a lot of duplicate references in465 the presence of cyclic links, and make performance quite bad.466 467 By default, a `**` in a pattern will follow 1 symbolic link if468 it is not the first item in the pattern, or none if it is the469 first item in the pattern, following the same behavior as Bash.470 471> [!NOTE]472> When `follow` and `nodir` are both set, then symbolic473> links to directories are also omitted.474 475- `realpath` Set to true to call `fs.realpath` on all of the476 results. In the case of an entry that cannot be resolved, the477 entry is omitted. This incurs a slight performance penalty, of478 course, because of the added system calls.479 480- `absolute` Set to true to always receive absolute paths for481 matched files. Set to `false` to always receive relative paths482 for matched files.483 484 By default, when this option is not set, absolute paths are485 returned for patterns that are absolute, and otherwise paths486 are returned that are relative to the `cwd` setting.487 488 This does _not_ make an extra system call to get the realpath,489 it only does string path resolution.490 491 `absolute` may not be used along with `withFileTypes`.492 493- `posix` Set to true to use `/` as the path separator in494 returned results. On POSIX systems, this has no effect. On495 Windows systems, this will return `/` delimited path results,496 and absolute paths will be returned in their fully resolved UNC497 path form, e.g. instead of `'C:\\foo\\bar'`, it will return498 `//?/C:/foo/bar`.499 500- `platform` Defaults to the value of `process.platform` if501 available, or `'linux'` if not. Setting `platform:'win32'` on502 non-Windows systems may cause strange behavior.503 504- `withFileTypes` Return505 [`path-scurry`](http://npm.im/path-scurry)506 [`Path`](https://isaacs.github.io/path-scurry/classes/PathBase.html)507 objects instead of strings. These are similar to a NodeJS508 `fs.Dirent` object, but with additional methods and properties.509 510 `withFileTypes` may not be used along with `absolute`.511 512- `signal` An AbortSignal which will cancel the Glob walk when513 triggered.514 515- `fs` An override object to pass in custom filesystem methods.516 See [`path-scurry`517 docs](https://isaacs.github.io/path-scurry/interfaces/FSOption.html)518 for what can be overridden.519 520- `scurry` A521 [`PathScurry`](https://isaacs.github.io/path-scurry/classes/PathScurryBase.html)522 object used to traverse the file system. If the `nocase` option523 is set explicitly, then any provided `scurry` object must match524 this setting.525 526- `includeChildMatches` boolean, default `true`. Do not match any527 children of any matches. For example, the pattern `**\/foo`528 would match `a/foo`, but not `a/foo/b/foo` in this mode.529 530 This is especially useful for cases like "find all531 `node_modules` folders, but not the ones in `node_modules`".532 533 In order to support this, the `Ignore` implementation must534 support an `add(pattern: string)` method. If using the default535 `Ignore` class, then this is fine, but if this is set to536 `false`, and a custom `Ignore` is provided that does not have537 an `add()` method, then it will throw an error.538 539 For example:540 541 ```js542 const results = await glob(543 [544 // likely to match first, since it's just a stat545 'a/b/c/d/e/f',546 547 // this pattern is more complicated! It must to various readdir()548 // calls and test the results against a regular expression, and that549 // is certainly going to take a little bit longer.550 //551 // So, later on, it encounters a match at 'a/b/c/d/e', but it's too552 // late to ignore a/b/c/d/e/f, because it's already been emitted.553 'a/[bdf]/?/[a-z]/*',554 ],555 { includeChildMatches: false },556 )557 ```558 559 It's best to only set this to `false` if you can be reasonably560 sure that no components of the pattern will potentially match561 one another's file system descendants, or if the occasional562 included child entry will not cause problems.563 564> [!NOTE]565> It _only_ ignores matches that would be a descendant566> of a previous match, and only if that descendant is matched567> _after_ the ancestor is encountered. Since the file system walk568> happens in indeterminate order, it's possible that a match will569> already be added before its ancestor, if multiple or braced570> patterns are used.571 572- `braceExpandMax` number, defaults to `10_000`. This is the573 maximum number of `{x,y,...}` patterns to expand. It is very574 unlikely that you'll need more than this, and setting it higher575 exposes the system to out-of-memory errors.576 577## Glob Primer578 579Much more information about glob pattern expansion can be found580by running `man bash` and searching for `Pattern Matching`.581 582"Globs" are the patterns you type when you do stuff like `ls583*.js` on the command line, or put `build/*` in a `.gitignore`584file.585 586Before parsing the path part patterns, braced sections are587expanded into a set. Braced sections start with `{` and end with588`}`, with 2 or more comma-delimited sections within. Braced589sections may contain slash characters, so `a{/b/c,bcd}` would590expand into `a/b/c` and `abcd`.591 592The following characters have special magic meaning when used in593a path portion. With the exception of `**`, none of these match594path separators (ie, `/` on all platforms, and `\` on Windows).595 596- `*` Matches 0 or more characters in a single path portion.597 When alone in a path portion, it must match at least 1598 character. If `dot:true` is not specified, then `*` will not599 match against a `.` character at the start of a path portion.600- `?` Matches 1 character. If `dot:true` is not specified, then601 `?` will not match against a `.` character at the start of a602 path portion.603- `[...]` Matches a range of characters, similar to a RegExp604 range. If the first character of the range is `!` or `^` then605 it matches any character not in the range. If the first606 character is `]`, then it will be considered the same as `\]`,607 rather than the end of the character class.608- `!(pattern|pattern|pattern)` Matches anything that does not609 match any of the patterns provided. May _not_ contain `/`610 characters. Similar to `*`, if alone in a path portion, then611 the path portion must have at least one character.612- `?(pattern|pattern|pattern)` Matches zero or one occurrence of613 the patterns provided. May _not_ contain `/` characters.614- `+(pattern|pattern|pattern)` Matches one or more occurrences of615 the patterns provided. May _not_ contain `/` characters.616- `*(a|b|c)` Matches zero or more occurrences of the patterns617 provided. May _not_ contain `/` characters.618- `@(pattern|pat*|pat?erN)` Matches exactly one of the patterns619 provided. May _not_ contain `/` characters.620- `**` If a "globstar" is alone in a path portion, then it621 matches zero or more directories and subdirectories searching622 for matches. It does not crawl symlinked directories, unless623 `{follow:true}` is passed in the options object. A pattern624 like `a/b/**` will only match `a/b` if it is a directory.625 Follows 1 symbolic link if not the first item in the pattern,626 or 0 if it is the first item, unless `follow:true` is set, in627 which case it follows all symbolic links.628 629`[:class:]` patterns are supported by this implementation, but630`[=c=]` and `[.symbol.]` style class patterns are not.631 632### Dots633 634If a file or directory path portion has a `.` as the first635character, then it will not match any glob pattern unless that636pattern's corresponding path part also has a `.` as its first637character.638 639For example, the pattern `a/.*/c` would match the file at640`a/.b/c`. However the pattern `a/*/c` would not, because `*` does641not start with a dot character.642 643You can make glob treat dots as normal characters by setting644`dot:true` in the options.645 646### Basename Matching647 648If you set `matchBase:true` in the options, and the pattern has649no slashes in it, then it will seek for any file anywhere in the650tree with a matching basename. For example, `*.js` would match651`test/simple/basic.js`.652 653### Empty Sets654 655If no matching files are found, then an empty array is returned.656This differs from the shell, where the pattern itself is657returned. For example:658 659```sh660$ echo a*s*d*f661a*s*d*f662```663 664## Comparisons to other fnmatch/glob implementations665 666While strict compliance with the existing standards is a667worthwhile goal, some discrepancies exist between node-glob and668other implementations, and are intentional.669 670The double-star character `**` is supported by default, unless671the `noglobstar` flag is set. This is supported in the manner of672bsdglob and bash 5, where `**` only has special significance if673it is the only thing in a path part. That is, `a/**/b` will match674`a/x/y/b`, but `a/**b` will not.675 676> [!NOTE]677> Symlinked directories are not traversed as part of a678> `**`, though their contents may match against subsequent portions679> of the pattern. This prevents infinite loops and duplicates and680> the like. You can force glob to traverse symlinks with `**` by681> setting `{follow:true}` in the options.682 683There is no equivalent of the `nonull` option. A pattern that684does not find any matches simply resolves to nothing. (An empty685array, immediately ended stream, etc.)686 687If brace expansion is not disabled, then it is performed before688any other interpretation of the glob pattern. Thus, a pattern689like `+(a|{b),c)}`, which would not be valid in bash or zsh, is690expanded **first** into the set of `+(a|b)` and `+(a|c)`, and691those patterns are checked for validity. Since those two are692valid, matching proceeds.693 694The character class patterns `[:class:]` (POSIX standard named695classes) style class patterns are supported and Unicode-aware,696but `[=c=]` (locale-specific character collation weight), and697`[.symbol.]` (collating symbol), are not.698 699### Repeated Slashes700 701Unlike Bash and zsh, repeated `/` are always coalesced into a702single path separator.703 704### Comments and Negation705 706Previously, this module let you mark a pattern as a "comment" if707it started with a `#` character, or a "negated" pattern if it708started with a `!` character.709 710These options were deprecated in version 5, and removed in711version 6.712 713To specify things that should not match, use the `ignore` option.714 715## Windows716 717**Please only use forward-slashes in glob expressions.**718 719Though Windows uses either `/` or `\` as its path separator, only720`/` characters are used by this glob implementation. You must use721forward-slashes **only** in glob expressions. Back-slashes will722always be interpreted as escape characters, not path separators.723 724Results from absolute patterns such as `/foo/*` are mounted onto725the root setting using `path.join`. On Windows, this will by726default result in `/foo/*` matching `C:\foo\bar.txt`.727 728To automatically coerce all `\` characters to `/` in pattern729strings, **thus making it impossible to escape literal glob730characters**, you may set the `windowsPathsNoEscape` option to731`true`.732 733### Windows, CWDs, Drive Letters, and UNC Paths734 735On POSIX systems, when a pattern starts with `/`, any `cwd`736option is ignored, and the traversal starts at `/`, plus any737non-magic path portions specified in the pattern.738 739On Windows systems, the behavior is similar, but the concept of740an "absolute path" is somewhat more involved.741 742#### UNC Paths743 744A UNC path may be used as the start of a pattern on Windows745platforms. For example, a pattern like: `//?/x:/*` will return746all file entries in the root of the `x:` drive. A pattern like747`//ComputerName/Share/*` will return all files in the associated748share.749 750UNC path roots are always compared case insensitively.751 752#### Drive Letters753 754A pattern starting with a drive letter, like `c:/*`, will search755in that drive, regardless of any `cwd` option provided.756 757If the pattern starts with `/`, and is not a UNC path, and there758is an explicit `cwd` option set with a drive letter, then the759drive letter in the `cwd` is used as the root of the directory760traversal.761 762For example, `glob('/tmp', { cwd: 'c:/any/thing' })` will return763`['c:/tmp']` as the result.764 765If an explicit `cwd` option is not provided, and the pattern766starts with `/`, then the traversal will run on the root of the767drive provided as the `cwd` option. (That is, it is the result of768`path.resolve('/')`.)769 770## Race Conditions771 772Glob searching, by its very nature, is susceptible to race773conditions, since it relies on directory walking.774 775As a result, it is possible that a file that exists when glob776looks for it may have been deleted or modified by the time it777returns the result.778 779By design, this implementation caches all readdir calls that it780makes, in order to cut down on system overhead. However, this781also makes it even more susceptible to races, especially if the782cache object is reused between glob calls.783 784Users are thus advised not to use a glob result as a guarantee of785filesystem state in the face of rapid changes. For the vast786majority of operations, this is never a problem.787 788### See Also:789 790- `man sh`791- `man bash` [Pattern792 Matching](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html)793- `man 3 fnmatch`794- `man 5 gitignore`795- [minimatch documentation](https://github.com/isaacs/minimatch)796 797## Glob Logo798 799Glob's logo was created by [Tanya800Brassie](http://tanyabrassie.com/). Logo files can be found801[here](https://github.com/isaacs/node-glob/tree/master/logo).802 803The logo is licensed under a [Creative Commons804Attribution-ShareAlike 4.0 International805License](https://creativecommons.org/licenses/by-sa/4.0/).806 807## Contributing808 809Any change to behavior (including bugfixes) must come with a810test.811 812Patches that fail tests or reduce performance will be rejected.813 814```sh815# to run tests816npm test817 818# to re-generate test fixtures819npm run test-regen820 821# run the benchmarks822npm run bench823 824# to profile javascript825npm run prof826```827 828## Comparison to Other JavaScript Glob Implementations829 830**tl;dr**831 832- If you want glob matching that is as faithful as possible to833 Bash pattern expansion semantics, and as fast as possible834 within that constraint, _use this module_.835- If you are reasonably sure that the patterns you will encounter836 are relatively simple, and want the absolutely fastest glob837 matcher out there, _use [fast-glob](http://npm.im/fast-glob)_.838- If you are reasonably sure that the patterns you will encounter839 are relatively simple, and want the convenience of840 automatically respecting `.gitignore` files, _use841 [globby](http://npm.im/globby)_.842 843There are some other glob matcher libraries on npm, but these844three are (in my opinion, as of 2023) the best.845 846---847 848**full explanation**849 850Every library reflects a set of opinions and priorities in the851trade-offs it makes. Other than this library, I can personally852recommend both [globby](http://npm.im/globby) and853[fast-glob](http://npm.im/fast-glob), though they differ in their854benefits and drawbacks.855 856Both have very nice APIs and are reasonably fast.857 858`fast-glob` is, as far as I am aware, the fastest glob859implementation in JavaScript today. However, there are many860cases where the choices that `fast-glob` makes in pursuit of861speed mean that its results differ from the results returned by862Bash and other sh-like shells, which may be surprising.863 864In my testing, `fast-glob` is around 10-20% faster than this865module when walking over 200k files nested 4 directories866deep[1](#fn-webscale). However, there are some inconsistencies867with Bash matching behavior that this module does not suffer868from:869 870- `**` only matches files, not directories871- `..` path portions are not handled unless they appear at the872 start of the pattern873- `./!(<pattern>)` will not match any files that _start_ with874 `<pattern>`, even if they do not match `<pattern>`. For875 example, `!(9).txt` will not match `9999.txt`.876- Some brace patterns in the middle of a pattern will result in877 failing to find certain matches.878- Extglob patterns are allowed to contain `/` characters.879 880Globby exhibits all of the same pattern semantics as fast-glob,881(as it is a wrapper around fast-glob) and is slightly slower than882node-glob (by about 10-20% in the benchmark test set, or in other883words, anywhere from 20-50% slower than fast-glob). However, it884adds some API conveniences that may be worth the costs.885 886- Support for `.gitignore` and other ignore files.887- Support for negated globs (ie, patterns starting with `!`888 rather than using a separate `ignore` option).889 890The priority of this module is "correctness" in the sense of891performing a glob pattern expansion as faithfully as possible to892the behavior of Bash and other sh-like shells, with as much speed893as possible.894 895> [!NOTE]896> Prior versions of `node-glob` are _not_ on this list.897> Former versions of this module are far too slow for any cases898> where performance matters at all, and were designed with APIs899> that are extremely dated by current JavaScript standards.900 901---902 903<small id="fn-webscale">[1]: In the cases where this module904returns results and `fast-glob` doesn't, it's even faster, of905course.</small>906 907908 909### Benchmark Results910 911The first number is time, smaller is better.912 913The second number is the count of results returned.914 915```916--- pattern: '**' ---917~~ sync ~~918node fast-glob sync 0m0.598s 200364919node globby sync 0m0.765s 200364920node current globSync mjs 0m0.683s 222656921node current glob syncStream 0m0.649s 222656922~~ async ~~923node fast-glob async 0m0.350s 200364924node globby async 0m0.509s 200364925node current glob async mjs 0m0.463s 222656926node current glob stream 0m0.411s 222656927 928--- pattern: '**/..' ---929~~ sync ~~930node fast-glob sync 0m0.486s 0931node globby sync 0m0.769s 200364932node current globSync mjs 0m0.564s 2242933node current glob syncStream 0m0.583s 2242934~~ async ~~935node fast-glob async 0m0.283s 0936node globby async 0m0.512s 200364937node current glob async mjs 0m0.299s 2242938node current glob stream 0m0.312s 2242939 940--- pattern: './**/0/**/0/**/0/**/0/**/*.txt' ---941~~ sync ~~942node fast-glob sync 0m0.490s 10943node globby sync 0m0.517s 10944node current globSync mjs 0m0.540s 10945node current glob syncStream 0m0.550s 10946~~ async ~~947node fast-glob async 0m0.290s 10948node globby async 0m0.296s 10949node current glob async mjs 0m0.278s 10950node current glob stream 0m0.302s 10951 952--- pattern: './**/[01]/**/[12]/**/[23]/**/[45]/**/*.txt' ---953~~ sync ~~954node fast-glob sync 0m0.500s 160955node globby sync 0m0.528s 160956node current globSync mjs 0m0.556s 160957node current glob syncStream 0m0.573s 160958~~ async ~~959node fast-glob async 0m0.283s 160960node globby async 0m0.301s 160961node current glob async mjs 0m0.306s 160962node current glob stream 0m0.322s 160963 964--- pattern: './**/0/**/0/**/*.txt' ---965~~ sync ~~966node fast-glob sync 0m0.502s 5230967node globby sync 0m0.527s 5230968node current globSync mjs 0m0.544s 5230969node current glob syncStream 0m0.557s 5230970~~ async ~~971node fast-glob async 0m0.285s 5230972node globby async 0m0.305s 5230973node current glob async mjs 0m0.304s 5230974node current glob stream 0m0.310s 5230975 976--- pattern: '**/*.txt' ---977~~ sync ~~978node fast-glob sync 0m0.580s 200023979node globby sync 0m0.771s 200023980node current globSync mjs 0m0.685s 200023981node current glob syncStream 0m0.649s 200023982~~ async ~~983node fast-glob async 0m0.349s 200023984node globby async 0m0.509s 200023985node current glob async mjs 0m0.427s 200023986node current glob stream 0m0.388s 200023987 988--- pattern: '{**/*.txt,**/?/**/*.txt,**/?/**/?/**/*.txt,**/?/**/?/**/?/**/*.txt,**/?/**/?/**/?/**/?/**/*.txt}' ---989~~ sync ~~990node fast-glob sync 0m0.589s 200023991node globby sync 0m0.771s 200023992node current globSync mjs 0m0.716s 200023993node current glob syncStream 0m0.684s 200023994~~ async ~~995node fast-glob async 0m0.351s 200023996node globby async 0m0.518s 200023997node current glob async mjs 0m0.462s 200023998node current glob stream 0m0.468s 200023999 1000--- pattern: '**/5555/0000/*.txt' ---1001~~ sync ~~1002node fast-glob sync 0m0.496s 10001003node globby sync 0m0.519s 10001004node current globSync mjs 0m0.539s 10001005node current glob syncStream 0m0.567s 10001006~~ async ~~1007node fast-glob async 0m0.285s 10001008node globby async 0m0.299s 10001009node current glob async mjs 0m0.305s 10001010node current glob stream 0m0.301s 10001011 1012--- pattern: './**/0/**/../[01]/**/0/../**/0/*.txt' ---1013~~ sync ~~1014node fast-glob sync 0m0.484s 01015node globby sync 0m0.507s 01016node current globSync mjs 0m0.577s 48801017node current glob syncStream 0m0.586s 48801018~~ async ~~1019node fast-glob async 0m0.280s 01020node globby async 0m0.298s 01021node current glob async mjs 0m0.327s 48801022node current glob stream 0m0.324s 48801023 1024--- pattern: '**/????/????/????/????/*.txt' ---1025~~ sync ~~1026node fast-glob sync 0m0.547s 1000001027node globby sync 0m0.673s 1000001028node current globSync mjs 0m0.626s 1000001029node current glob syncStream 0m0.618s 1000001030~~ async ~~1031node fast-glob async 0m0.315s 1000001032node globby async 0m0.414s 1000001033node current glob async mjs 0m0.366s 1000001034node current glob stream 0m0.345s 1000001035 1036--- pattern: './{**/?{/**/?{/**/?{/**/?,,,,},,,,},,,,},,,}/**/*.txt' ---1037~~ sync ~~1038node fast-glob sync 0m0.588s 1000001039node globby sync 0m0.670s 1000001040node current globSync mjs 0m0.717s 2000231041node current glob syncStream 0m0.687s 2000231042~~ async ~~1043node fast-glob async 0m0.343s 1000001044node globby async 0m0.418s 1000001045node current glob async mjs 0m0.519s 2000231046node current glob stream 0m0.451s 2000231047 1048--- pattern: '**/!(0|9).txt' ---1049~~ sync ~~1050node fast-glob sync 0m0.573s 1600231051node globby sync 0m0.731s 1600231052node current globSync mjs 0m0.680s 1800231053node current glob syncStream 0m0.659s 1800231054~~ async ~~1055node fast-glob async 0m0.345s 1600231056node globby async 0m0.476s 1600231057node current glob async mjs 0m0.427s 1800231058node current glob stream 0m0.388s 1800231059 1060--- pattern: './{*/**/../{*/**/../{*/**/../{*/**/../{*/**,,,,},,,,},,,,},,,,},,,,}/*.txt' ---1061~~ sync ~~1062node fast-glob sync 0m0.483s 01063node globby sync 0m0.512s 01064node current globSync mjs 0m0.811s 2000231065node current glob syncStream 0m0.773s 2000231066~~ async ~~1067node fast-glob async 0m0.280s 01068node globby async 0m0.299s 01069node current glob async mjs 0m0.617s 2000231070node current glob stream 0m0.568s 2000231071 1072--- pattern: './*/**/../*/**/../*/**/../*/**/../*/**/../*/**/../*/**/../*/**/*.txt' ---1073~~ sync ~~1074node fast-glob sync 0m0.485s 01075node globby sync 0m0.507s 01076node current globSync mjs 0m0.759s 2000231077node current glob syncStream 0m0.740s 2000231078~~ async ~~1079node fast-glob async 0m0.281s 01080node globby async 0m0.297s 01081node current glob async mjs 0m0.544s 2000231082node current glob stream 0m0.464s 2000231083 1084--- pattern: './*/**/../*/**/../*/**/../*/**/../*/**/*.txt' ---1085~~ sync ~~1086node fast-glob sync 0m0.486s 01087node globby sync 0m0.513s 01088node current globSync mjs 0m0.734s 2000231089node current glob syncStream 0m0.696s 2000231090~~ async ~~1091node fast-glob async 0m0.286s 01092node globby async 0m0.296s 01093node current glob async mjs 0m0.506s 2000231094node current glob stream 0m0.483s 2000231095 1096--- pattern: './0/**/../1/**/../2/**/../3/**/../4/**/../5/**/../6/**/../7/**/*.txt' ---1097~~ sync ~~1098node fast-glob sync 0m0.060s 01099node globby sync 0m0.074s 01100node current globSync mjs 0m0.067s 01101node current glob syncStream 0m0.066s 01102~~ async ~~1103node fast-glob async 0m0.060s 01104node globby async 0m0.075s 01105node current glob async mjs 0m0.066s 01106node current glob stream 0m0.067s 01107 1108--- pattern: './**/?/**/?/**/?/**/?/**/*.txt' ---1109~~ sync ~~1110node fast-glob sync 0m0.568s 1000001111node globby sync 0m0.651s 1000001112node current globSync mjs 0m0.619s 1000001113node current glob syncStream 0m0.617s 1000001114~~ async ~~1115node fast-glob async 0m0.332s 1000001116node globby async 0m0.409s 1000001117node current glob async mjs 0m0.372s 1000001118node current glob stream 0m0.351s 1000001119 1120--- pattern: '**/*/**/*/**/*/**/*/**' ---1121~~ sync ~~1122node fast-glob sync 0m0.603s 2001131123node globby sync 0m0.798s 2001131124node current globSync mjs 0m0.730s 2221371125node current glob syncStream 0m0.693s 2221371126~~ async ~~1127node fast-glob async 0m0.356s 2001131128node globby async 0m0.525s 2001131129node current glob async mjs 0m0.508s 2221371130node current glob stream 0m0.455s 2221371131 1132--- pattern: './**/*/**/*/**/*/**/*/**/*.txt' ---1133~~ sync ~~1134node fast-glob sync 0m0.622s 2000001135node globby sync 0m0.792s 2000001136node current globSync mjs 0m0.722s 2000001137node current glob syncStream 0m0.695s 2000001138~~ async ~~1139node fast-glob async 0m0.369s 2000001140node globby async 0m0.527s 2000001141node current glob async mjs 0m0.502s 2000001142node current glob stream 0m0.481s 2000001143 1144--- pattern: '**/*.txt' ---1145~~ sync ~~1146node fast-glob sync 0m0.588s 2000231147node globby sync 0m0.771s 2000231148node current globSync mjs 0m0.684s 2000231149node current glob syncStream 0m0.658s 2000231150~~ async ~~1151node fast-glob async 0m0.352s 2000231152node globby async 0m0.516s 2000231153node current glob async mjs 0m0.432s 2000231154node current glob stream 0m0.384s 2000231155 1156--- pattern: './**/**/**/**/**/**/**/**/*.txt' ---1157~~ sync ~~1158node fast-glob sync 0m0.589s 2000231159node globby sync 0m0.766s 2000231160node current globSync mjs 0m0.682s 2000231161node current glob syncStream 0m0.652s 2000231162~~ async ~~1163node fast-glob async 0m0.352s 2000231164node globby async 0m0.523s 2000231165node current glob async mjs 0m0.436s 2000231166node current glob stream 0m0.380s 2000231167 1168--- pattern: '**/*/*.txt' ---1169~~ sync ~~1170node fast-glob sync 0m0.592s 2000231171node globby sync 0m0.776s 2000231172node current globSync mjs 0m0.691s 2000231173node current glob syncStream 0m0.659s 2000231174~~ async ~~1175node fast-glob async 0m0.357s 2000231176node globby async 0m0.513s 2000231177node current glob async mjs 0m0.471s 2000231178node current glob stream 0m0.424s 2000231179 1180--- pattern: '**/*/**/*.txt' ---1181~~ sync ~~1182node fast-glob sync 0m0.585s 2000231183node globby sync 0m0.766s 2000231184node current globSync mjs 0m0.694s 2000231185node current glob syncStream 0m0.664s 2000231186~~ async ~~1187node fast-glob async 0m0.350s 2000231188node globby async 0m0.514s 2000231189node current glob async mjs 0m0.472s 2000231190node current glob stream 0m0.424s 2000231191 1192--- pattern: '**/[0-9]/**/*.txt' ---1193~~ sync ~~1194node fast-glob sync 0m0.544s 1000001195node globby sync 0m0.636s 1000001196node current globSync mjs 0m0.626s 1000001197node current glob syncStream 0m0.621s 1000001198~~ async ~~1199node fast-glob async 0m0.322s 1000001200node globby async 0m0.404s 100000