Brunobkr/llama.cpp_AlgMor24_github

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 10![a fun cartoon logo made of glob11characters](https://github.com/isaacs/node-glob/raw/main/logo/glob.png)12 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 153```154$ glob -h155 156Usage:157  glob [options] [<pattern> [<pattern> ...]]158 159Expand the positional glob expression arguments into any matching file system160paths found.161 162  -c<command> --cmd=<command>163                         Run the command provided, passing the glob expression164                         matches as arguments.165 166  -A --all               By default, the glob cli command will not expand any167                         arguments that are an exact match to a file on disk.168 169                         This prevents double-expanding, in case the shell170                         expands an argument whose filename is a glob171                         expression.172 173                         For example, if 'app/*.ts' would match 'app/[id].ts',174                         then on Windows powershell or cmd.exe, 'glob app/*.ts'175                         will expand to 'app/[id].ts', as expected. However, in176                         posix shells such as bash or zsh, the shell will first177                         expand 'app/*.ts' to a list of filenames. Then glob178                         will look for a file matching 'app/[id].ts' (ie,179                         'app/i.ts' or 'app/d.ts'), which is unexpected.180 181                         Setting '--all' prevents this behavior, causing glob to182                         treat ALL patterns as glob expressions to be expanded,183                         even if they are an exact match to a file on disk.184 185                         When setting this option, be sure to enquote arguments186                         so that the shell will not expand them prior to passing187                         them to the glob command process.188 189  -a --absolute          Expand to absolute paths190  -d --dot-relative      Prepend './' on relative matches191  -m --mark              Append a / on any directories matched192  -x --posix             Always resolve to posix style paths, using '/' as the193                         directory separator, even on Windows. Drive letter194                         absolute matches on Windows will be expanded to their195                         full resolved UNC paths, eg instead of 'C:\foo\bar', it196                         will expand to '//?/C:/foo/bar'.197 198  -f --follow            Follow symlinked directories when expanding '**'199  -R --realpath          Call 'fs.realpath' on all of the results. In the case200                         of an entry that cannot be resolved, the entry is201                         omitted. This incurs a slight performance penalty, of202                         course, because of the added system calls.203 204  -s --stat              Call 'fs.lstat' on all entries, whether required or not205                         to determine if it's a valid match.206 207  -b --match-base        Perform a basename-only match if the pattern does not208                         contain any slash characters. That is, '*.js' would be209                         treated as equivalent to '**/*.js', matching js files210                         in all directories.211 212  --dot                  Allow patterns to match files/directories that start213                         with '.', even if the pattern does not start with '.'214 215  --nobrace              Do not expand {...} patterns216  --nocase               Perform a case-insensitive match. This defaults to217                         'true' on macOS and Windows platforms, and false on all218                         others.219 220                         Note: 'nocase' should only be explicitly set when it is221                         known that the filesystem's case sensitivity differs222                         from the platform default. If set 'true' on223                         case-insensitive file systems, then the walk may return224                         more or less results than expected.225 226  --nodir                Do not match directories, only files.227 228                         Note: to *only* match directories, append a '/' at the229                         end of the pattern.230 231  --noext                Do not expand extglob patterns, such as '+(a|b)'232  --noglobstar           Do not expand '**' against multiple path portions. Ie,233                         treat it as a normal '*' instead.234 235  --windows-path-no-escape236                         Use '\' as a path separator *only*, and *never* as an237                         escape character. If set, all '\' characters are238                         replaced with '/' in the pattern.239 240  -D<n> --max-depth=<n>  Maximum depth to traverse from the current working241                         directory242 243  -C<cwd> --cwd=<cwd>    Current working directory to execute/match in244  -r<root> --root=<root> A string path resolved against the 'cwd', which is used245                         as the starting point for absolute patterns that start246                         with '/' (but not drive letters or UNC paths on247                         Windows).248 249                         Note that this *doesn't* necessarily limit the walk to250                         the 'root' directory, and doesn't affect the cwd251                         starting point for non-absolute patterns. A pattern252                         containing '..' will still be able to traverse out of253                         the root directory, if it is not an actual root254                         directory on the filesystem, and any non-absolute255                         patterns will still be matched in the 'cwd'.256 257                         To start absolute and non-absolute patterns in the same258                         path, you can use '--root=' to set it to the empty259                         string. However, be aware that on Windows systems, a260                         pattern like 'x:/*' or '//host/share/*' will *always*261                         start in the 'x:/' or '//host/share/' directory,262                         regardless of the --root setting.263 264  --platform=<platform>  Defaults to the value of 'process.platform' if265                         available, or 'linux' if not. Setting --platform=win32266                         on non-Windows systems may cause strange behavior!267 268  -i<ignore> --ignore=<ignore>269                         Glob patterns to ignore Can be set multiple times270  -v --debug             Output a huge amount of noisy debug information about271                         patterns as they are parsed and used to match files.272 273  -h --help              Show this usage information274```275 276## `glob(pattern: string | string[], options?: GlobOptions) => Promise<string[] | Path[]>`277 278Perform an asynchronous glob search for the pattern(s) specified.279Returns280[Path](https://isaacs.github.io/path-scurry/classes/PathBase)281objects if the `withFileTypes` option is set to `true`. See below282for full options field desciptions.283 284## `globSync(pattern: string | string[], options?: GlobOptions) => string[] | Path[]`285 286Synchronous form of `glob()`.287 288Alias: `glob.sync()`289 290## `globIterate(pattern: string | string[], options?: GlobOptions) => AsyncGenerator<string>`291 292Return an async iterator for walking glob pattern matches.293 294Alias: `glob.iterate()`295 296## `globIterateSync(pattern: string | string[], options?: GlobOptions) => Generator<string>`297 298Return a sync iterator for walking glob pattern matches.299 300Alias: `glob.iterate.sync()`, `glob.sync.iterate()`301 302## `globStream(pattern: string | string[], options?: GlobOptions) => Minipass<string | Path>`303 304Return a stream that emits all the strings or `Path` objects and305then emits `end` when completed.306 307Alias: `glob.stream()`308 309## `globStreamSync(pattern: string | string[], options?: GlobOptions) => Minipass<string | Path>`310 311Syncronous form of `globStream()`. Will read all the matches as312fast as you consume them, even all in a single tick if you313consume them immediately, but will still respond to backpressure314if they're not consumed immediately.315 316Alias: `glob.stream.sync()`, `glob.sync.stream()`317 318## `hasMagic(pattern: string | string[], options?: GlobOptions) => boolean`319 320Returns `true` if the provided pattern contains any "magic" glob321characters, given the options provided.322 323Brace expansion is not considered "magic" unless the324`magicalBraces` option is set, as brace expansion just turns one325string into an array of strings. So a pattern like `'x{a,b}y'`326would return `false`, because `'xay'` and `'xby'` both do not327contain any magic glob characters, and it's treated the same as328if you had called it on `['xay', 'xby']`. When329`magicalBraces:true` is in the options, brace expansion _is_330treated as a pattern having magic.331 332## `escape(pattern: string, options?: GlobOptions) => string`333 334Escape all magic characters in a glob pattern, so that it will335only ever match literal strings336 337If the `windowsPathsNoEscape` option is used, then characters are338escaped by wrapping in `[]`, because a magic character wrapped in339a character class can only be satisfied by that exact character.340 341Slashes (and backslashes in `windowsPathsNoEscape` mode) cannot342be escaped or unescaped.343 344## `unescape(pattern: string, options?: GlobOptions) => string`345 346Un-escape a glob string that may contain some escaped characters.347 348If the `windowsPathsNoEscape` option is used, then square-brace349escapes are removed, but not backslash escapes. For example, it350will turn the string `'[*]'` into `*`, but it will not turn351`'\\*'` into `'*'`, because `\` is a path separator in352`windowsPathsNoEscape` mode.353 354When `windowsPathsNoEscape` is not set, then both brace escapes355and backslash escapes are removed.356 357Slashes (and backslashes in `windowsPathsNoEscape` mode) cannot358be escaped or unescaped.359 360## Class `Glob`361 362An object that can perform glob pattern traversals.363 364### `const g = new Glob(pattern: string | string[], options: GlobOptions)`365 366Options object is required.367 368See full options descriptions below.369 370> [!NOTE]371> A previous `Glob` object can be passed as the372> `GlobOptions` to another `Glob` instantiation to re-use settings373> and caches with a new pattern.374 375Traversal functions can be called multiple times to run the walk376again.377 378### `g.stream()`379 380Stream results asynchronously.381 382### `g.streamSync()`383 384Stream results synchronously.385 386### `g.iterate()`387 388Default async iteration function. Returns an AsyncGenerator that389iterates over the results.390 391### `g.iterateSync()`392 393Default sync iteration function. Returns a Generator that394iterates over the results.395 396### `g.walk()`397 398Returns a Promise that resolves to the results array.399 400### `g.walkSync()`401 402Returns a results array.403 404### Properties405 406All options are stored as properties on the `Glob` object.407 408- `opts` The options provided to the constructor.409- `patterns` An array of parsed immutable `Pattern` objects.410 411## Options412 413Exported as `GlobOptions` TypeScript interface. A `GlobOptions`414object may be provided to any of the exported methods, and must415be provided to the `Glob` constructor.416 417All options are optional, boolean, and false by default, unless418otherwise noted.419 420All resolved options are added to the Glob object as properties.421 422If you are running many `glob` operations, you can pass a Glob423object as the `options` argument to a subsequent operation to424share the previously loaded cache.425 426- `cwd` String path or `file://` string or URL object. The427  current working directory in which to search. Defaults to428  `process.cwd()`. See also: "Windows, CWDs, Drive Letters, and429  UNC Paths", below.430 431  This option may be either a string path or a `file://` URL432  object or string.433 434- `root` A string path resolved against the `cwd` option, which435  is used as the starting point for absolute patterns that start436  with `/`, (but not drive letters or UNC paths on Windows).437 438    To start absolute and non-absolute patterns in the same path,439    you can use `{root:''}`. However, be aware that on Windows440    systems, a pattern like `x:/*` or `//host/share/*` will441    _always_ start in the `x:/` or `//host/share` directory,442    regardless of the `root` setting.443 444> [!NOTE] This _doesn't_ necessarily limit the walk to the445> `root` directory, and doesn't affect the cwd starting point446> for non-absolute patterns. A pattern containing `..` will447> still be able to traverse out of the root directory, if it448> is not an actual root directory on the filesystem, and any449> non-absolute patterns will be matched in the `cwd`. For450> example, the pattern `/../*` with `{root:'/some/path'}`451> will return all files in `/some`, not all files in452> `/some/path`. The pattern `*` with `{root:'/some/path'}`453> will return all the entries in the cwd, not the entries in454> `/some/path`.455 456- `windowsPathsNoEscape` Use `\\` as a path separator _only_, and457  _never_ as an escape character. If set, all `\\` characters are458  replaced with `/` in the pattern.459 460> [!NOTE]461> This makes it **impossible** to match against paths462> containing literal glob pattern characters, but allows matching463> with patterns constructed using `path.join()` and464> `path.resolve()` on Windows platforms, mimicking the (buggy!)465> behavior of Glob v7 and before on Windows. Please use with466> caution, and be mindful of [the caveat below about Windows467> paths](#windows). (For legacy reasons, this is also set if468> `allowWindowsEscape` is set to the exact value `false`.)469 470- `dot` Include `.dot` files in normal matches and `globstar`471  matches. Note that an explicit dot in a portion of the pattern472  will always match dot files.473 474- `magicalBraces` Treat brace expansion like `{a,b}` as a "magic"475  pattern. Has no effect if {@link nobrace} is set.476 477  Only has effect on the {@link hasMagic} function, no effect on478  glob pattern matching itself.479 480- `dotRelative` Prepend all relative path strings with `./` (or481  `.\` on Windows).482 483  Without this option, returned relative paths are "bare", so484  instead of returning `'./foo/bar'`, they are returned as485  `'foo/bar'`.486 487  Relative patterns starting with `'../'` are not prepended with488  `./`, even if this option is set.489 490- `mark` Add a `/` character to directory matches. Note that this491  requires additional stat calls.492 493- `nobrace` Do not expand `{a,b}` and `{1..3}` brace sets.494 495- `noglobstar` Do not match `**` against multiple filenames. (Ie,496  treat it as a normal `*` instead.)497 498- `noext` Do not match "extglob" patterns such as `+(a|b)`.499 500- `nocase` Perform a case-insensitive match. This defaults to501  `true` on macOS and Windows systems, and `false` on all others.502 503> [!NOTE]504> `nocase` should only be explicitly set when it is505> known that the filesystem's case sensitivity differs from the506> platform default. If set `true` on case-sensitive file507> systems, or `false` on case-insensitive file systems, then the508> walk may return more or less results than expected.509 510- `maxDepth` Specify a number to limit the depth of the directory511  traversal to this many levels below the `cwd`.512 513- `matchBase` Perform a basename-only match if the pattern does514  not contain any slash characters. That is, `*.js` would be515  treated as equivalent to `**/*.js`, matching all js files in516  all directories.517 518- `nodir` Do not match directories, only files. (Note: to match519  _only_ directories, put a `/` at the end of the pattern.)520 521> [!NOTE]522> When `follow` and `nodir` are both set, then symbolic523> links to directories are also omitted.524 525- `stat` Call `lstat()` on all entries, whether required or not526  to determine whether it's a valid match. When used with527  `withFileTypes`, this means that matches will include data such528  as modified time, permissions, and so on. Note that this will529  incur a performance cost due to the added system calls.530 531- `ignore` string or string[], or an object with `ignored` and532  `childrenIgnored` methods.533 534  If a string or string[] is provided, then this is treated as535  a glob pattern or array of glob patterns to exclude from536  matches. To ignore all children within a directory, as well537  as the entry itself, append `'/**'` to the ignore pattern.538 539  If an object is provided that has `ignored(path)` and/or540  `childrenIgnored(path)` methods, then these methods will be541  called to determine whether any Path is a match or if its542  children should be traversed, respectively.543 544  The `path` argument to the methods will be a545  [`path-scurry`](https://isaacs.github.io/path-scurry/index.html)546  [`Path`](https://isaacs.github.io/path-scurry/classes/PathBase)547  object, which extends548  [`fs.Dirent`](https://nodejs.org/docs/latest/api/fs.html#class-fsdirent)549  with additional useful methods like550  [`.fullpath()`](https://isaacs.github.io/path-scurry/classes/PathBase.html#fullpath),551  [`.relative()`](https://isaacs.github.io/path-scurry/classes/PathBase.html#relative),552  and more.553 554> [!NOTE]555> `ignore` patterns are _always_ in `dot:true` mode,556> regardless of any other settings.557 558- `follow` Follow symlinked directories when expanding `**`559  patterns. This can result in a lot of duplicate references in560  the presence of cyclic links, and make performance quite bad.561 562  By default, a `**` in a pattern will follow 1 symbolic link if563  it is not the first item in the pattern, or none if it is the564  first item in the pattern, following the same behavior as Bash.565 566> [!NOTE]567> When `follow` and `nodir` are both set, then symbolic568> links to directories are also omitted.569 570- `realpath` Set to true to call `fs.realpath` on all of the571  results. In the case of an entry that cannot be resolved, the572  entry is omitted. This incurs a slight performance penalty, of573  course, because of the added system calls.574 575- `absolute` Set to true to always receive absolute paths for576  matched files. Set to `false` to always receive relative paths577  for matched files.578 579  By default, when this option is not set, absolute paths are580  returned for patterns that are absolute, and otherwise paths581  are returned that are relative to the `cwd` setting.582 583  This does _not_ make an extra system call to get the realpath,584  it only does string path resolution.585 586  `absolute` may not be used along with `withFileTypes`.587 588- `posix` Set to true to use `/` as the path separator in589  returned results. On POSIX systems, this has no effect. On590  Windows systems, this will return `/` delimited path results,591  and absolute paths will be returned in their fully resolved UNC592  path form, e.g. instead of `'C:\\foo\\bar'`, it will return593  `//?/C:/foo/bar`.594 595- `platform` Defaults to the value of `process.platform` if596  available, or `'linux'` if not. Setting `platform:'win32'` on597  non-Windows systems may cause strange behavior.598 599- `withFileTypes` Return600  [`path-scurry`](http://npm.im/path-scurry)601  [`Path`](https://isaacs.github.io/path-scurry/classes/PathBase.html)602  objects instead of strings. These are similar to a NodeJS603  `fs.Dirent` object, but with additional methods and properties.604 605  `withFileTypes` may not be used along with `absolute`.606 607- `signal` An AbortSignal which will cancel the Glob walk when608  triggered.609 610- `fs` An override object to pass in custom filesystem methods.611  See [`path-scurry`612  docs](https://isaacs.github.io/path-scurry/interfaces/FSOption.html)613  for what can be overridden.614 615- `scurry` A616  [`PathScurry`](https://isaacs.github.io/path-scurry/classes/PathScurryBase.html)617  object used to traverse the file system. If the `nocase` option618  is set explicitly, then any provided `scurry` object must match619  this setting.620 621- `includeChildMatches` boolean, default `true`. Do not match any622  children of any matches. For example, the pattern `**\/foo`623  would match `a/foo`, but not `a/foo/b/foo` in this mode.624 625  This is especially useful for cases like "find all626  `node_modules` folders, but not the ones in `node_modules`".627 628  In order to support this, the `Ignore` implementation must629  support an `add(pattern: string)` method. If using the default630  `Ignore` class, then this is fine, but if this is set to631  `false`, and a custom `Ignore` is provided that does not have632  an `add()` method, then it will throw an error.633 634  For example:635 636  ```js637  const results = await glob(638    [639      // likely to match first, since it's just a stat640      'a/b/c/d/e/f',641 642      // this pattern is more complicated! It must to various readdir()643      // calls and test the results against a regular expression, and that644      // is certainly going to take a little bit longer.645      //646      // So, later on, it encounters a match at 'a/b/c/d/e', but it's too647      // late to ignore a/b/c/d/e/f, because it's already been emitted.648      'a/[bdf]/?/[a-z]/*',649    ],650    { includeChildMatches: false },651  )652  ```653 654  It's best to only set this to `false` if you can be reasonably655  sure that no components of the pattern will potentially match656  one another's file system descendants, or if the occasional657  included child entry will not cause problems.658 659> [!NOTE]660> It _only_ ignores matches that would be a descendant661> of a previous match, and only if that descendant is matched662> _after_ the ancestor is encountered. Since the file system walk663> happens in indeterminate order, it's possible that a match will664> already be added before its ancestor, if multiple or braced665> patterns are used.666 667 668## Glob Primer669 670Much more information about glob pattern expansion can be found671by running `man bash` and searching for `Pattern Matching`.672 673"Globs" are the patterns you type when you do stuff like `ls674*.js` on the command line, or put `build/*` in a `.gitignore`675file.676 677Before parsing the path part patterns, braced sections are678expanded into a set. Braced sections start with `{` and end with679`}`, with 2 or more comma-delimited sections within. Braced680sections may contain slash characters, so `a{/b/c,bcd}` would681expand into `a/b/c` and `abcd`.682 683The following characters have special magic meaning when used in684a path portion. With the exception of `**`, none of these match685path separators (ie, `/` on all platforms, and `\` on Windows).686 687- `*` Matches 0 or more characters in a single path portion.688  When alone in a path portion, it must match at least 1689  character. If `dot:true` is not specified, then `*` will not690  match against a `.` character at the start of a path portion.691- `?` Matches 1 character. If `dot:true` is not specified, then692  `?` will not match against a `.` character at the start of a693  path portion.694- `[...]` Matches a range of characters, similar to a RegExp695  range. If the first character of the range is `!` or `^` then696  it matches any character not in the range. If the first697  character is `]`, then it will be considered the same as `\]`,698  rather than the end of the character class.699- `!(pattern|pattern|pattern)` Matches anything that does not700  match any of the patterns provided. May _not_ contain `/`701  characters. Similar to `*`, if alone in a path portion, then702  the path portion must have at least one character.703- `?(pattern|pattern|pattern)` Matches zero or one occurrence of704  the patterns provided. May _not_ contain `/` characters.705- `+(pattern|pattern|pattern)` Matches one or more occurrences of706  the patterns provided. May _not_ contain `/` characters.707- `*(a|b|c)` Matches zero or more occurrences of the patterns708  provided. May _not_ contain `/` characters.709- `@(pattern|pat*|pat?erN)` Matches exactly one of the patterns710  provided. May _not_ contain `/` characters.711- `**` If a "globstar" is alone in a path portion, then it712  matches zero or more directories and subdirectories searching713  for matches. It does not crawl symlinked directories, unless714  `{follow:true}` is passed in the options object. A pattern715  like `a/b/**` will only match `a/b` if it is a directory.716  Follows 1 symbolic link if not the first item in the pattern,717  or 0 if it is the first item, unless `follow:true` is set, in718  which case it follows all symbolic links.719 720`[:class:]` patterns are supported by this implementation, but721`[=c=]` and `[.symbol.]` style class patterns are not.722 723### Dots724 725If a file or directory path portion has a `.` as the first726character, then it will not match any glob pattern unless that727pattern's corresponding path part also has a `.` as its first728character.729 730For example, the pattern `a/.*/c` would match the file at731`a/.b/c`. However the pattern `a/*/c` would not, because `*` does732not start with a dot character.733 734You can make glob treat dots as normal characters by setting735`dot:true` in the options.736 737### Basename Matching738 739If you set `matchBase:true` in the options, and the pattern has740no slashes in it, then it will seek for any file anywhere in the741tree with a matching basename. For example, `*.js` would match742`test/simple/basic.js`.743 744### Empty Sets745 746If no matching files are found, then an empty array is returned.747This differs from the shell, where the pattern itself is748returned. For example:749 750```sh751$ echo a*s*d*f752a*s*d*f753```754 755## Comparisons to other fnmatch/glob implementations756 757While strict compliance with the existing standards is a758worthwhile goal, some discrepancies exist between node-glob and759other implementations, and are intentional.760 761The double-star character `**` is supported by default, unless762the `noglobstar` flag is set. This is supported in the manner of763bsdglob and bash 5, where `**` only has special significance if764it is the only thing in a path part. That is, `a/**/b` will match765`a/x/y/b`, but `a/**b` will not.766 767> [!NOTE]768> Symlinked directories are not traversed as part of a769> `**`, though their contents may match against subsequent portions770> of the pattern. This prevents infinite loops and duplicates and771> the like. You can force glob to traverse symlinks with `**` by772> setting `{follow:true}` in the options.773 774There is no equivalent of the `nonull` option. A pattern that775does not find any matches simply resolves to nothing. (An empty776array, immediately ended stream, etc.)777 778If brace expansion is not disabled, then it is performed before779any other interpretation of the glob pattern. Thus, a pattern780like `+(a|{b),c)}`, which would not be valid in bash or zsh, is781expanded **first** into the set of `+(a|b)` and `+(a|c)`, and782those patterns are checked for validity. Since those two are783valid, matching proceeds.784 785The character class patterns `[:class:]` (POSIX standard named786classes) style class patterns are supported and Unicode-aware,787but `[=c=]` (locale-specific character collation weight), and788`[.symbol.]` (collating symbol), are not.789 790### Repeated Slashes791 792Unlike Bash and zsh, repeated `/` are always coalesced into a793single path separator.794 795### Comments and Negation796 797Previously, this module let you mark a pattern as a "comment" if798it started with a `#` character, or a "negated" pattern if it799started with a `!` character.800 801These options were deprecated in version 5, and removed in802version 6.803 804To specify things that should not match, use the `ignore` option.805 806## Windows807 808**Please only use forward-slashes in glob expressions.**809 810Though Windows uses either `/` or `\` as its path separator, only811`/` characters are used by this glob implementation. You must use812forward-slashes **only** in glob expressions. Back-slashes will813always be interpreted as escape characters, not path separators.814 815Results from absolute patterns such as `/foo/*` are mounted onto816the root setting using `path.join`. On Windows, this will by817default result in `/foo/*` matching `C:\foo\bar.txt`.818 819To automatically coerce all `\` characters to `/` in pattern820strings, **thus making it impossible to escape literal glob821characters**, you may set the `windowsPathsNoEscape` option to822`true`.823 824### Windows, CWDs, Drive Letters, and UNC Paths825 826On POSIX systems, when a pattern starts with `/`, any `cwd`827option is ignored, and the traversal starts at `/`, plus any828non-magic path portions specified in the pattern.829 830On Windows systems, the behavior is similar, but the concept of831an "absolute path" is somewhat more involved.832 833#### UNC Paths834 835A UNC path may be used as the start of a pattern on Windows836platforms. For example, a pattern like: `//?/x:/*` will return837all file entries in the root of the `x:` drive. A pattern like838`//ComputerName/Share/*` will return all files in the associated839share.840 841UNC path roots are always compared case insensitively.842 843#### Drive Letters844 845A pattern starting with a drive letter, like `c:/*`, will search846in that drive, regardless of any `cwd` option provided.847 848If the pattern starts with `/`, and is not a UNC path, and there849is an explicit `cwd` option set with a drive letter, then the850drive letter in the `cwd` is used as the root of the directory851traversal.852 853For example, `glob('/tmp', { cwd: 'c:/any/thing' })` will return854`['c:/tmp']` as the result.855 856If an explicit `cwd` option is not provided, and the pattern857starts with `/`, then the traversal will run on the root of the858drive provided as the `cwd` option. (That is, it is the result of859`path.resolve('/')`.)860 861## Race Conditions862 863Glob searching, by its very nature, is susceptible to race864conditions, since it relies on directory walking.865 866As a result, it is possible that a file that exists when glob867looks for it may have been deleted or modified by the time it868returns the result.869 870By design, this implementation caches all readdir calls that it871makes, in order to cut down on system overhead. However, this872also makes it even more susceptible to races, especially if the873cache object is reused between glob calls.874 875Users are thus advised not to use a glob result as a guarantee of876filesystem state in the face of rapid changes. For the vast877majority of operations, this is never a problem.878 879### See Also:880 881- `man sh`882- `man bash` [Pattern883  Matching](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html)884- `man 3 fnmatch`885- `man 5 gitignore`886- [minimatch documentation](https://github.com/isaacs/minimatch)887 888## Glob Logo889 890Glob's logo was created by [Tanya891Brassie](http://tanyabrassie.com/). Logo files can be found892[here](https://github.com/isaacs/node-glob/tree/master/logo).893 894The logo is licensed under a [Creative Commons895Attribution-ShareAlike 4.0 International896License](https://creativecommons.org/licenses/by-sa/4.0/).897 898## Contributing899 900Any change to behavior (including bugfixes) must come with a901test.902 903Patches that fail tests or reduce performance will be rejected.904 905```sh906# to run tests907npm test908 909# to re-generate test fixtures910npm run test-regen911 912# run the benchmarks913npm run bench914 915# to profile javascript916npm run prof917```918 919## Comparison to Other JavaScript Glob Implementations920 921**tl;dr**922 923- If you want glob matching that is as faithful as possible to924  Bash pattern expansion semantics, and as fast as possible925  within that constraint, _use this module_.926- If you are reasonably sure that the patterns you will encounter927  are relatively simple, and want the absolutely fastest glob928  matcher out there, _use [fast-glob](http://npm.im/fast-glob)_.929- If you are reasonably sure that the patterns you will encounter930  are relatively simple, and want the convenience of931  automatically respecting `.gitignore` files, _use932  [globby](http://npm.im/globby)_.933 934There are some other glob matcher libraries on npm, but these935three are (in my opinion, as of 2023) the best.936 937---938 939**full explanation**940 941Every library reflects a set of opinions and priorities in the942trade-offs it makes. Other than this library, I can personally943recommend both [globby](http://npm.im/globby) and944[fast-glob](http://npm.im/fast-glob), though they differ in their945benefits and drawbacks.946 947Both have very nice APIs and are reasonably fast.948 949`fast-glob` is, as far as I am aware, the fastest glob950implementation in JavaScript today. However, there are many951cases where the choices that `fast-glob` makes in pursuit of952speed mean that its results differ from the results returned by953Bash and other sh-like shells, which may be surprising.954 955In my testing, `fast-glob` is around 10-20% faster than this956module when walking over 200k files nested 4 directories957deep[1](#fn-webscale). However, there are some inconsistencies958with Bash matching behavior that this module does not suffer959from:960 961- `**` only matches files, not directories962- `..` path portions are not handled unless they appear at the963  start of the pattern964- `./!(<pattern>)` will not match any files that _start_ with965  `<pattern>`, even if they do not match `<pattern>`. For966  example, `!(9).txt` will not match `9999.txt`.967- Some brace patterns in the middle of a pattern will result in968  failing to find certain matches.969- Extglob patterns are allowed to contain `/` characters.970 971Globby exhibits all of the same pattern semantics as fast-glob,972(as it is a wrapper around fast-glob) and is slightly slower than973node-glob (by about 10-20% in the benchmark test set, or in other974words, anywhere from 20-50% slower than fast-glob). However, it975adds some API conveniences that may be worth the costs.976 977- Support for `.gitignore` and other ignore files.978- Support for negated globs (ie, patterns starting with `!`979  rather than using a separate `ignore` option).980 981The priority of this module is "correctness" in the sense of982performing a glob pattern expansion as faithfully as possible to983the behavior of Bash and other sh-like shells, with as much speed984as possible.985 986> [!NOTE]987> Prior versions of `node-glob` are _not_ on this list.988> Former versions of this module are far too slow for any cases989> where performance matters at all, and were designed with APIs990> that are extremely dated by current JavaScript standards.991 992---993 994<small id="fn-webscale">[1]: In the cases where this module995returns results and `fast-glob` doesn't, it's even faster, of996course.</small>997 998![lumpy space princess saying 'oh my GLOB'](https://github.com/isaacs/node-glob/raw/main/oh-my-glob.gif)999 1000### Benchmark Results1001 1002The first number is time, smaller is better.1003 1004The second number is the count of results returned.1005 1006```1007--- pattern: '**' ---1008~~ sync ~~1009node fast-glob sync             0m0.598s  2003641010node globby sync                0m0.765s  2003641011node current globSync mjs       0m0.683s  2226561012node current glob syncStream    0m0.649s  2226561013~~ async ~~1014node fast-glob async            0m0.350s  2003641015node globby async               0m0.509s  2003641016node current glob async mjs     0m0.463s  2226561017node current glob stream        0m0.411s  2226561018 1019--- pattern: '**/..' ---1020~~ sync ~~1021node fast-glob sync             0m0.486s  01022node globby sync                0m0.769s  2003641023node current globSync mjs       0m0.564s  22421024node current glob syncStream    0m0.583s  22421025~~ async ~~1026node fast-glob async            0m0.283s  01027node globby async               0m0.512s  2003641028node current glob async mjs     0m0.299s  22421029node current glob stream        0m0.312s  22421030 1031--- pattern: './**/0/**/0/**/0/**/0/**/*.txt' ---1032~~ sync ~~1033node fast-glob sync             0m0.490s  101034node globby sync                0m0.517s  101035node current globSync mjs       0m0.540s  101036node current glob syncStream    0m0.550s  101037~~ async ~~1038node fast-glob async            0m0.290s  101039node globby async               0m0.296s  101040node current glob async mjs     0m0.278s  101041node current glob stream        0m0.302s  101042 1043--- pattern: './**/[01]/**/[12]/**/[23]/**/[45]/**/*.txt' ---1044~~ sync ~~1045node fast-glob sync             0m0.500s  1601046node globby sync                0m0.528s  1601047node current globSync mjs       0m0.556s  1601048node current glob syncStream    0m0.573s  1601049~~ async ~~1050node fast-glob async            0m0.283s  1601051node globby async               0m0.301s  1601052node current glob async mjs     0m0.306s  1601053node current glob stream        0m0.322s  1601054 1055--- pattern: './**/0/**/0/**/*.txt' ---1056~~ sync ~~1057node fast-glob sync             0m0.502s  52301058node globby sync                0m0.527s  52301059node current globSync mjs       0m0.544s  52301060node current glob syncStream    0m0.557s  52301061~~ async ~~1062node fast-glob async            0m0.285s  52301063node globby async               0m0.305s  52301064node current glob async mjs     0m0.304s  52301065node current glob stream        0m0.310s  52301066 1067--- pattern: '**/*.txt' ---1068~~ sync ~~1069node fast-glob sync             0m0.580s  2000231070node globby sync                0m0.771s  2000231071node current globSync mjs       0m0.685s  2000231072node current glob syncStream    0m0.649s  2000231073~~ async ~~1074node fast-glob async            0m0.349s  2000231075node globby async               0m0.509s  2000231076node current glob async mjs     0m0.427s  2000231077node current glob stream        0m0.388s  2000231078 1079--- pattern: '{**/*.txt,**/?/**/*.txt,**/?/**/?/**/*.txt,**/?/**/?/**/?/**/*.txt,**/?/**/?/**/?/**/?/**/*.txt}' ---1080~~ sync ~~1081node fast-glob sync             0m0.589s  2000231082node globby sync                0m0.771s  2000231083node current globSync mjs       0m0.716s  2000231084node current glob syncStream    0m0.684s  2000231085~~ async ~~1086node fast-glob async            0m0.351s  2000231087node globby async               0m0.518s  2000231088node current glob async mjs     0m0.462s  2000231089node current glob stream        0m0.468s  2000231090 1091--- pattern: '**/5555/0000/*.txt' ---1092~~ sync ~~1093node fast-glob sync             0m0.496s  10001094node globby sync                0m0.519s  10001095node current globSync mjs       0m0.539s  10001096node current glob syncStream    0m0.567s  10001097~~ async ~~1098node fast-glob async            0m0.285s  10001099node globby async               0m0.299s  10001100node current glob async mjs     0m0.305s  10001101node current glob stream        0m0.301s  10001102 1103--- pattern: './**/0/**/../[01]/**/0/../**/0/*.txt' ---1104~~ sync ~~1105node fast-glob sync             0m0.484s  01106node globby sync                0m0.507s  01107node current globSync mjs       0m0.577s  48801108node current glob syncStream    0m0.586s  48801109~~ async ~~1110node fast-glob async            0m0.280s  01111node globby async               0m0.298s  01112node current glob async mjs     0m0.327s  48801113node current glob stream        0m0.324s  48801114 1115--- pattern: '**/????/????/????/????/*.txt' ---1116~~ sync ~~1117node fast-glob sync             0m0.547s  1000001118node globby sync                0m0.673s  1000001119node current globSync mjs       0m0.626s  1000001120node current glob syncStream    0m0.618s  1000001121~~ async ~~1122node fast-glob async            0m0.315s  1000001123node globby async               0m0.414s  1000001124node current glob async mjs     0m0.366s  1000001125node current glob stream        0m0.345s  1000001126 1127--- pattern: './{**/?{/**/?{/**/?{/**/?,,,,},,,,},,,,},,,}/**/*.txt' ---1128~~ sync ~~1129node fast-glob sync             0m0.588s  1000001130node globby sync                0m0.670s  1000001131node current globSync mjs       0m0.717s  2000231132node current glob syncStream    0m0.687s  2000231133~~ async ~~1134node fast-glob async            0m0.343s  1000001135node globby async               0m0.418s  1000001136node current glob async mjs     0m0.519s  2000231137node current glob stream        0m0.451s  2000231138 1139--- pattern: '**/!(0|9).txt' ---1140~~ sync ~~1141node fast-glob sync             0m0.573s  1600231142node globby sync                0m0.731s  1600231143node current globSync mjs       0m0.680s  1800231144node current glob syncStream    0m0.659s  1800231145~~ async ~~1146node fast-glob async            0m0.345s  1600231147node globby async               0m0.476s  1600231148node current glob async mjs     0m0.427s  1800231149node current glob stream        0m0.388s  1800231150 1151--- pattern: './{*/**/../{*/**/../{*/**/../{*/**/../{*/**,,,,},,,,},,,,},,,,},,,,}/*.txt' ---1152~~ sync ~~1153node fast-glob sync             0m0.483s  01154node globby sync                0m0.512s  01155node current globSync mjs       0m0.811s  2000231156node current glob syncStream    0m0.773s  2000231157~~ async ~~1158node fast-glob async            0m0.280s  01159node globby async               0m0.299s  01160node current glob async mjs     0m0.617s  2000231161node current glob stream        0m0.568s  2000231162 1163--- pattern: './*/**/../*/**/../*/**/../*/**/../*/**/../*/**/../*/**/../*/**/*.txt' ---1164~~ sync ~~1165node fast-glob sync             0m0.485s  01166node globby sync                0m0.507s  01167node current globSync mjs       0m0.759s  2000231168node current glob syncStream    0m0.740s  2000231169~~ async ~~1170node fast-glob async            0m0.281s  01171node globby async               0m0.297s  01172node current glob async mjs     0m0.544s  2000231173node current glob stream        0m0.464s  2000231174 1175--- pattern: './*/**/../*/**/../*/**/../*/**/../*/**/*.txt' ---1176~~ sync ~~1177node fast-glob sync             0m0.486s  01178node globby sync                0m0.513s  01179node current globSync mjs       0m0.734s  2000231180node current glob syncStream    0m0.696s  2000231181~~ async ~~1182node fast-glob async            0m0.286s  01183node globby async               0m0.296s  01184node current glob async mjs     0m0.506s  2000231185node current glob stream        0m0.483s  2000231186 1187--- pattern: './0/**/../1/**/../2/**/../3/**/../4/**/../5/**/../6/**/../7/**/*.txt' ---1188~~ sync ~~1189node fast-glob sync             0m0.060s  01190node globby sync                0m0.074s  01191node current globSync mjs       0m0.067s  01192node current glob syncStream    0m0.066s  01193~~ async ~~1194node fast-glob async            0m0.060s  01195node globby async               0m0.075s  01196node current glob async mjs     0m0.066s  01197node current glob stream        0m0.067s  01198 1199--- pattern: './**/?/**/?/**/?/**/?/**/*.txt' ---1200~~ sync ~~

Showing the first 1,200 of 1295 lines. Download the file for the rest.