All options are stored as properties on the Glob object.
See GlobOptions for full options descriptions.
Note that a previous Glob object can be passed as the
GlobOptions to another Glob instantiation to re-use settings
and caches with a new pattern.
Traversal functions can be called multiple times to run the walk again.
OptionalabsoluteSet 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
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.
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.
Optionalignorestring 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 })
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.
OptionalmarkAdd 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
The options provided to the constructor.
An array of parsed immutable Pattern objects.
Defaults to value of process.platform if available, or 'linux' if
not. Setting platform:'win32' on non-Windows systems may cause strange
behavior.
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.
OptionalrootA 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.
OptionalsignalAn 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
An object that can perform glob pattern traversals.