Interface GlobOptions

Set to true to always receive absolute paths for matched files. Set to false to always return relative paths.

When this option is not set, absolute paths are returned for patterns that are absolute, and otherwise paths are returned that are relative to the cwd setting.

This does not make an extra system call to get the realpath, it only does string path resolution.

Conflicts with withFileTypes

Set to false to enable windowsPathsNoEscape

The current working directory in which to search. Defaults to process.cwd().

May be eiher a string path or a file:// URL object or string.

Just passed along to Minimatch. Note that this makes all pattern matching operations slower and extremely noisy.

Include .dot files in normal matches and globstar matches. Note that an explicit dot in a portion of the pattern will always match dot files.

Prepend all relative path strings with ./ (or .\ on Windows).

Without this option, returned relative paths are "bare", so instead of returning './foo/bar', they are returned as 'foo/bar'.

Relative patterns starting with '../' are not prepended with ./, even if this option is set.

Follow symlinked directories when expanding ** patterns. This can result in a lot of duplicate references in the presence of cyclic links, and make performance quite bad.

By default, a ** in a pattern will follow 1 symbolic link if it is not the first item in the pattern, or none if it is the first item in the pattern, following the same behavior as Bash.

An fs implementation to override some or all of the defaults. See http://npm.im/path-scurry for details about what can be overridden.

string or string[], or an object with ignored and childrenIgnored methods.

If a string or string[] is provided, then this is treated as a glob pattern or array of glob patterns to exclude from matches. To ignore all children within a directory, as well as the entry itself, append '/**' to the ignore pattern.

Note ignore patterns are always in dot:true mode, regardless of any other settings.

If an object is provided that has ignored(path) and/or childrenIgnored(path) methods, then these methods will be called to determine whether any Path is a match or if its children should be traversed, respectively.

Do not match any children of any matches. For example, the pattern **/foo would match a/foo, but not a/foo/b/foo in this mode.

This is especially useful for cases like "find all node_modules folders, but not the ones in node_modules".

In order to support this, the Ignore implementation must support an add(pattern: string) method. If using the default Ignore class, then this is fine, but if this is set to false, and a custom Ignore is provided that does not have an add() method, then it will throw an error.

Caveat It only ignores matches that would be a descendant of a previous match, and only if that descendant is matched after the ancestor is encountered. Since the file system walk happens in indeterminate order, it's possible that a match will already be added before its ancestor, if multiple or braced patterns are used.

For example:

const results = await glob([
  // likely to match first, since it's just a stat
  'a/b/c/d/e/f',

  // this pattern is more complicated! It must to various readdir()
  // calls and test the results against a regular expression, and that
  // is certainly going to take a little bit longer.
  //
  // So, later on, it encounters a match at 'a/b/c/d/e', but it's too
  // late to ignore a/b/c/d/e/f, because it's already been emitted.
  'a/[bdf]/?/[a-z]/*',
], { includeChildMatches: false })
Copy

It's best to only set this to false if you can be reasonably sure that no components of the pattern will potentially match one another's file system descendants, or if the occasional included child entry will not cause problems.

Treat brace expansion like {a,b} as a "magic" pattern. Has no effect if nobrace is set.

Only has effect on the hasMagic function.

Add a / character to directory matches. Note that this requires additional stat calls in some cases.

Perform a basename-only match if the pattern does not contain any slash characters. That is, *.js would be treated as equivalent to **/*.js, matching all js files in all directories.

Limit the directory traversal to a given depth below the cwd. Note that this does NOT prevent traversal to sibling folders, root patterns, and so on. It only limits the maximum folder depth that the walk will descend, relative to the cwd.

Do not expand {a,b} and {1..3} brace sets.

Perform a case-insensitive match. This defaults to true on macOS and Windows systems, and false on all others.

Note nocase should only be explicitly set when it is known that the filesystem's case sensitivity differs from the platform default. If set true on case-sensitive file systems, or false on case-insensitive file systems, then the walk may return more or less results than expected.

Do not match directories, only files. (Note: to match only directories, put a / at the end of the pattern.)

Do not match "extglob" patterns such as +(a|b).

Do not match ** against multiple filenames. (Ie, treat it as a normal * instead.)

Conflicts with matchBase

Defaults to value of process.platform if available, or 'linux' if not. Setting platform:'win32' on non-Windows systems may cause strange behavior.

Return / delimited paths, even on Windows.

On posix systems, this has no effect. But, on Windows, it means that paths will be / delimited, and absolute paths will be their full resolved UNC forms, eg instead of 'C:\\foo\\bar', it would return '//?/C:/foo/bar'

Set to true to call fs.realpath on all of the results. In the case of an entry that cannot be resolved, the entry is omitted. This incurs a slight performance penalty, of course, because of the added system calls.

A string path resolved against the cwd option, which is used as the starting point for absolute patterns that start with /, (but not drive letters or UNC paths on Windows).

Note that this doesn't necessarily limit the walk to the root directory, and doesn't affect the cwd starting point for non-absolute patterns. A pattern containing .. will still be able to traverse out of the root directory, if it is not an actual root directory on the filesystem, and any non-absolute patterns will be matched in the cwd. For example, the pattern /../* with {root:'/some/path'} will return all files in /some, not all files in /some/path. The pattern * with {root:'/some/path'} will return all the entries in the cwd, not the entries in /some/path.

To start absolute and non-absolute patterns in the same path, you can use {root:''}. However, be aware that on Windows systems, a pattern like x:/* or //host/share/* will always start in the x:/ or //host/share directory, regardless of the root setting.

A PathScurry object used to traverse the file system. If the nocase option is set explicitly, then any provided scurry object must match this setting.

An AbortSignal which will cancel the Glob walk when triggered.

Call lstat() on all entries, whether required or not to determine if it's a valid match. When used with withFileTypes, this means that matches will include data such as modified time, permissions, and so on. Note that this will incur a performance cost due to the added system calls.

Use \\ as a path separator only, and never as an escape character. If set, all \\ characters are replaced with / in the pattern.

Note that this makes it impossible to match against paths containing literal glob pattern characters, but allows matching with patterns constructed using path.join() and path.resolve() on Windows platforms, mimicking the (buggy!) behavior of Glob v7 and before on Windows. Please use with caution, and be mindful of the caveat below about Windows paths. (For legacy reasons, this is also set if allowWindowsEscape is set to the exact value false.)

Return PathScurry Path objects instead of strings. These are similar to a NodeJS Dirent object, but with additional methods and properties.

Conflicts with absolute