Glob

Match files using the patterns the shell uses.

The most correct and second fastest glob implementation in JavaScript. (SeeComparison to Other JavaScript Glob Implementationsat the bottom of this readme.)

Usage

Install with npm

npm i glob

Notethe npm package name isnotnode-globthat's a different thing that was abandoned years ago. Justglob.

// load using import
import{glob,globSync,globStream,globStreamSync,Glob}from'glob'
// or using commonjs, that's fine, too
const{
glob,
globSync,
globStream,
globStreamSync,
Glob,
}=require('glob')

// the main glob() and globSync() resolve/return array of filenames

// all js files, but don't look in node_modules
constjsfiles=awaitglob('**/*.js',{ignore:'node_modules/**'})

// pass in a signal to cancel the glob walk
conststopAfter100ms=awaitglob('**/*.css',{
signal:AbortSignal.timeout(100),
})

// multiple patterns supported as well
constimages=awaitglob(['css/*.{png,jpeg}','public/*.{png,jpeg}'])

// but of course you can do that with the glob pattern also
// the sync function is the same, just returns a string[] instead
// of Promise<string[]>
constimagesAlt=globSync('{css,public}/*.{png,jpeg}')

// you can also stream them, this is a Minipass stream
constfilesStream=globStream(['**/*.dat','logs/**/*.log'])

// construct a Glob object if you wanna do it that way, which
// allows for much faster walks if you have to look in the same
// folder multiple times.
constg=newGlob('**/foo',{})
// glob objects are async iterators, can also do globIterate() or
// g.iterate(), same deal
forawait(constfileofg){
console.log('found a foo file:',file)
}
// pass a glob as the glob options to reuse its settings and caches
constg2=newGlob('**/bar',g)
// sync iteration works as well
for(constfileofg2){
console.log('found a bar file:',file)
}

// you can also pass withFileTypes: true to get Path objects
// these are like a Dirent, but with some more added powers
// check out http://npm.im/path-scurry for more info on their API
constg3=newGlob('**/baz/**',{withFileTypes:true})
g3.stream().on('data',path=>{
console.log(
'got a path object',
path.fullpath(),
path.isDirectory(),
path.readdirSync().map(e=>e.name),
)
})

// if you use stat:true and withFileTypes, you can sort results
// by things like modified time, filter by permission mode, etc.
// All Stats fields will be available in that case. Slightly
// slower, though.
// For example:
constresults=awaitglob('**',{stat:true,withFileTypes:true})

consttimeSortedFiles=results
.sort((a,b)=>a.mtimeMs-b.mtimeMs)
.map(path=>path.fullpath())

constgroupReadableFiles=results
.filter(path=>path.mode&0o040)
.map(path=>path.fullpath())

// custom ignores can be done like this, for example by saying
// you'll ignore all markdown files, and all folders named 'docs'
constcustomIgnoreResults=awaitglob('**',{
ignore:{
ignored:p=>/\.md$/.test(p.name),
childrenIgnored:p=>p.isNamed('docs'),
},
})

// another fun use case, only return files with the same name as
// their parent folder, plus either `.ts` or `.js`
constfolderNamedModules=awaitglob('**/*.{ts,js}',{
ignore:{
ignored:p=>{
constpp=p.parent
return!(p.isNamed(pp.name+'.ts')||p.isNamed(pp.name+'.js'))
},
},
})

// find all files edited in the last hour, to do this, we ignore
// all of them that are more than an hour old
constnewFiles=awaitglob('**',{
// need stat so we have mtime
stat:true,
// only want the files, not the dirs
nodir:true,
ignore:{
ignored:p=>{
returnnewDate()-p.mtime>60*60*1000
},
// could add similar childrenIgnored here as well, but
// directory mtime is inconsistent across platforms, so
// probably better not to, unless you know the system
// tracks this reliably.
},
})

NoteGlob patterns should always use/as a path separator, even on Windows systems, as\is used to escape glob characters. If you wish to use\as a path separatorinstead ofusing it as an escape character on Windows platforms, you may setwindowsPathsNoEscape:truein the options. In this mode, special glob characters cannot be escaped, making it impossible to match a literal*?and so on in filenames.

Command Line Interface

$ glob -h

Usage:
glob [options] [<pattern> [<pattern>...]]

Expand the positional glob expression arguments into any matching file system
paths found.

-c<command> --cmd=<command>
Run the command provided, passing the glob expression
matches as arguments.

-A --all By default, the glob cli command will not expand any
arguments that are an exact match to a file on disk.

This prevents double-expanding, in case the shell
expands an argument whose filename is a glob
expression.

For example, if 'app/*.ts' would match 'app/[id].ts',
then on Windows powershell or cmd.exe, 'glob app/*.ts'
will expand to 'app/[id].ts', as expected. However, in
posix shells such as bash or zsh, the shell will first
expand 'app/*.ts' to a list of filenames. Then glob
will look for a file matching 'app/[id].ts' (ie,
'app/i.ts' or 'app/d.ts'), which is unexpected.

Setting '--all' prevents this behavior, causing glob to
treat ALL patterns as glob expressions to be expanded,
even if they are an exact match to a file on disk.

When setting this option, be sure to enquote arguments
so that the shell will not expand them prior to passing
them to the glob command process.

-a --absolute Expand to absolute paths
-d --dot-relative Prepend './' on relative matches
-m --mark Append a / on any directories matched
-x --posix Always resolve to posix style paths, using '/' as the
directory separator, even on Windows. Drive letter
absolute matches on Windows will be expanded to their
full resolved UNC maths, eg instead of 'C:\foo\bar', it
will expand to '//?/C:/foo/bar'.

-f --follow Follow symlinked directories when expanding '**'
-R --realpath 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.

-s --stat Call 'fs.lstat' on all entries, whether required or not
to determine if it's a valid match.

-b --match-base 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 js files
in all directories.

--dot Allow patterns to match files/directories that start
with '.', even if the pattern does not start with '.'

--nobrace Do not expand {...} patterns
--nocase Perform a case-insensitive match. This defaults to
'true' on macOS and Windows platforms, 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-insensitive file systems, then the walk may return
more or less results than expected.

--nodir Do not match directories, only files.

Note: to *only* match directories, append a '/' at the
end of the pattern.

--noext Do not expand extglob patterns, such as '+(a|b)'
--noglobstar Do not expand '**' against multiple path portions. Ie,
treat it as a normal '*' instead.

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

-D<n> --max-depth=<n> Maximum depth to traverse from the current working
directory

-C<cwd> --cwd=<cwd> Current working directory to execute/match in
-r<root> --root=<root> A string path resolved against the 'cwd', 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 still be matched in the 'cwd'.

To start absolute and non-absolute patterns in the same
path, you can use '--root=' to set it to the empty
string. 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.

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

-i<ignore> --ignore=<ignore>
Glob patterns to ignore Can be set multiple times
-v --debug Output a huge amount of noisy debug information about
patterns as they are parsed and used to match files.

-h --help Show this usage information

`glob(pattern: string | string[], options?: GlobOptions) => Promise<string[] | Path[]>`

Perform an asynchronous glob search for the pattern(s) specified. Returns Path objects if thewithFileTypesoption is set totrue.See below for full options field desciptions.

`globSync(pattern: string | string[], options?: GlobOptions) => string[] | Path[]`

Synchronous form ofglob().

Alias:glob.sync()

`globIterate(pattern: string | string[], options?: GlobOptions) => AsyncGenerator<string>`

Return an async iterator for walking glob pattern matches.

Alias:glob.iterate()

`globIterateSync(pattern: string | string[], options?: GlobOptions) => Generator<string>`

Return a sync iterator for walking glob pattern matches.

Alias:glob.iterate.sync(),glob.sync.iterate()

`globStream(pattern: string | string[], options?: GlobOptions) => Minipass<string | Path>`

Return a stream that emits all the strings orPathobjects and then emitsendwhen completed.

Alias:glob.stream()

`globStreamSync(pattern: string | string[], options?: GlobOptions) => Minipass<string | Path>`

Syncronous form ofglobStream().Will read all the matches as fast as you consume them, even all in a single tick if you consume them immediately, but will still respond to backpressure if they're not consumed immediately.

Alias:glob.stream.sync(),glob.sync.stream()

`hasMagic(pattern: string | string[], options?: GlobOptions) => boolean`

Returnstrueif the provided pattern contains any "magic" glob characters, given the options provided.

Brace expansion is not considered "magic" unless the magicalBracesoption is set, as brace expansion just turns one string into an array of strings. So a pattern like'x{a,b}y' would returnfalse,because'xay'and'xby'both do not contain any magic glob characters, and it's treated the same as if you had called it on['xay', 'xby'].When magicalBraces:trueis in the options, brace expansionis treated as a pattern having magic.

`escape(pattern: string, options?: GlobOptions) => string`

Escape all magic characters in a glob pattern, so that it will only ever match literal strings

If thewindowsPathsNoEscapeoption is used, then characters are escaped by wrapping in[],because a magic character wrapped in a character class can only be satisfied by that exact character.

Slashes (and backslashes inwindowsPathsNoEscapemode) cannot be escaped or unescaped.

`unescape(pattern: string, options?: GlobOptions) => string`

Un-escape a glob string that may contain some escaped characters.

If thewindowsPathsNoEscapeoption is used, then square-brace escapes are removed, but not backslash escapes. For example, it will turn the string'[*]'into*,but it will not turn '\\*'into'*',because\is a path separator in windowsPathsNoEscapemode.

WhenwindowsPathsNoEscapeis not set, then both brace escapes and backslash escapes are removed.

Slashes (and backslashes inwindowsPathsNoEscapemode) cannot be escaped or unescaped.

Class`Glob`

An object that can perform glob pattern traversals.

`const g = new Glob(pattern: string | string[], options: GlobOptions)`

Options object is required.

See full options descriptions below.

Note that a previousGlobobject can be passed as the GlobOptionsto anotherGlobinstantiation to re-use settings and caches with a new pattern.

Traversal functions can be called multiple times to run the walk again.

`g.stream()`

Stream results asynchronously,

`g.streamSync()`

Stream results synchronously.

`g.iterate()`

Default async iteration function. Returns an AsyncGenerator that iterates over the results.

`g.iterateSync()`

Default sync iteration function. Returns a Generator that iterates over the results.

`g.walk()`

Returns a Promise that resolves to the results array.

`g.walkSync()`

Returns a results array.

Properties

All options are stored as properties on theGlobobject.

optsThe options provided to the constructor.
patternsAn array of parsed immutablePatternobjects.

Options

Exported asGlobOptionsTypeScript interface. AGlobOptions object may be provided to any of the exported methods, and must be provided to theGlobconstructor.

All options are optional, boolean, and false by default, unless otherwise noted.

All resolved options are added to the Glob object as properties.

If you are running manygloboperations, you can pass a Glob object as theoptionsargument to a subsequent operation to share the previously loaded cache.

cwdString path orfile://string or URL object. The current working directory in which to search. Defaults to process.cwd().See also: "Windows, CWDs, Drive Letters, and UNC Paths", below.

This option may be either a string path or afile://URL object or string.
rootA string path resolved against thecwdoption, which is used as the starting point for absolute patterns that start with/,(but not drive letters or UNC paths on Windows).

Note that thisdoesn'tnecessarily limit the walk to the rootdirectory, 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 thecwd.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 likex:/*or//host/share/*will alwaysstart in thex:/or//host/sharedirectory, regardless of therootsetting.
windowsPathsNoEscapeUse\\as a path separatoronly,and neveras an escape character. If set, all\\characters are replaced with/in the pattern.

Note that this makes itimpossibleto match against paths containing literal glob pattern characters, but allows matching with patterns constructed usingpath.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 ofthe caveat below about Windows paths.(For legacy reasons, this is also set if allowWindowsEscapeis set to the exact valuefalse.)
dotInclude.dotfiles in normal matches andglobstar matches. Note that an explicit dot in a portion of the pattern will always match dot files.
magicalBracesTreat brace expansion like{a,b}as a "magic" pattern. Has no effect if {@link nobrace} is set.

Only has effect on the {@link hasMagic} function, no effect on glob pattern matching itself.
dotRelativePrepend 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.
markAdd a/character to directory matches. Note that this requires additional stat calls.
nobraceDo not expand{a,b}and{1..3}brace sets.
noglobstarDo not match**against multiple filenames. (Ie, treat it as a normal*instead.)
noextDo not match "extglob" patterns such as+(a|b).
nocasePerform a case-insensitive match. This defaults to trueon macOS and Windows systems, andfalseon all others.

Notenocaseshould only be explicitly set when it is known that the filesystem's case sensitivity differs from the platform default. If settrueon case-sensitive file systems, orfalseon case-insensitive file systems, then the walk may return more or less results than expected.
maxDepthSpecify a number to limit the depth of the directory traversal to this many levels below thecwd.
matchBasePerform a basename-only match if the pattern does not contain any slash characters. That is,*.jswould be treated as equivalent to**/*.js,matching all js files in all directories.
nodirDo not match directories, only files. (Note: to match onlydirectories, put a/at the end of the pattern.)

Note: whenfollowandnodirare both set, then symbolic links to directories are also omitted.
statCalllstat()on all entries, whether required or not to determine whether 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.
ignorestring or string[], or an object withignoredand childrenIgnoredmethods.

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.

Noteignorepatterns arealwaysindot:truemode, regardless of any other settings.

If an object is provided that hasignored(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.
followFollow 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.

Note: whenfollowandnodirare both set, then symbolic links to directories are also omitted.
realpathSet to true to callfs.realpathon 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.
absoluteSet to true to always receive absolute paths for matched files. Set tofalseto always receive relative paths for matched files.

By default, when this option is not set, absolute paths are returned for patterns that are absolute, and otherwise paths are returned that are relative to thecwdsetting.

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

absolutemay not be used along withwithFileTypes.
posixSet to true to use/as the path separator in returned results. On posix systems, this has no effect. On Windows systems, this will return/delimited path results, and absolute paths will be returned in their full resolved UNC path form, eg insted of'C:\\foo\\bar',it will return //?/C:/foo/bar.
platformDefaults to value ofprocess.platformif available, or'linux'if not. Settingplatform:'win32'on non-Windows systems may cause strange behavior.
withFileTypesReturnPathScurry Pathobjects instead of strings. These are similar to a NodeJSDirentobject, but with additional methods and properties.

withFileTypesmay not be used along withabsolute.
signalAn AbortSignal which will cancel the Glob walk when triggered.
fsAn override object to pass in custom filesystem methods. SeePathScurry docsfor what can be overridden.
scurryAPathScurryobject used to traverse the file system. If thenocaseoption is set explicitly, then any providedscurryobject must match this setting.
includeChildMatchesboolean, defaulttrue.Do not match any children of any matches. For example, the pattern**\/foo would matcha/foo,but nota/foo/b/fooin this mode.

This is especially useful for cases like "find all node_modulesfolders, but not the ones innode_modules".

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

CaveatItonlyignores matches that would be a descendant of a previous match, and only if that descendant is matched afterthe 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:
```
constresults=awaitglob(
[
// 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 tofalseif 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.

Glob Primer

Much more information about glob pattern expansion can be found by runningman bashand searching forPattern Matching.

"Globs" are the patterns you type when you do stuff likels *.json the command line, or putbuild/*in a.gitignore file.

Before parsing the path part patterns, braced sections are expanded into a set. Braced sections start with{and end with },with 2 or more comma-delimited sections within. Braced sections may contain slash characters, soa{/b/c,bcd}would expand intoa/b/candabcd.

The following characters have special magic meaning when used in a path portion. With the exception of**,none of these match path separators (ie,/on all platforms, and\on Windows).

*Matches 0 or more characters in a single path portion. When alone in a path portion, it must match at least 1 character. Ifdot:trueis not specified, then*will not match against a.character at the start of a path portion.
?Matches 1 character. Ifdot:trueis not specified, then ?will not match against a.character at the start of a path portion.
[...]Matches a range of characters, similar to a RegExp range. If the first character of the range is!or^then it matches any character not in the range. If the first character is],then it will be considered the same as\], rather than the end of the character class.
!(pattern|pattern|pattern)Matches anything that does not match any of the patterns provided. Maynotcontain/ characters. Similar to*,if alone in a path portion, then the path portion must have at least one character.
?(pattern|pattern|pattern)Matches zero or one occurrence of the patterns provided. Maynotcontain/characters.
+(pattern|pattern|pattern)Matches one or more occurrences of the patterns provided. Maynotcontain/characters.
*(a|b|c)Matches zero or more occurrences of the patterns provided. Maynotcontain/characters.
@(pattern|pat*|pat?erN)Matches exactly one of the patterns provided. Maynotcontain/characters.
**If a "globstar" is alone in a path portion, then it matches zero or more directories and subdirectories searching for matches. It does not crawl symlinked directories, unless {follow:true}is passed in the options object. A pattern likea/b/**will only matcha/bif it is a directory. Follows 1 symbolic link if not the first item in the pattern, or 0 if it is the first item, unlessfollow:trueis set, in which case it follows all symbolic links.

[:class:]patterns are supported by this implementation, but [=c=]and[.symbol.]style class patterns are not.

Dots

If a file or directory path portion has a.as the first character, then it will not match any glob pattern unless that pattern's corresponding path part also has a.as its first character.

For example, the patterna/.*/cwould match the file at a/.b/c.However the patterna/*/cwould not, because*does not start with a dot character.

You can make glob treat dots as normal characters by setting dot:truein the options.

Basename Matching

If you setmatchBase:truein the options, and the pattern has no slashes in it, then it will seek for any file anywhere in the tree with a matching basename. For example,*.jswould match test/simple/basic.js.

Empty Sets

If no matching files are found, then an empty array is returned. This differs from the shell, where the pattern itself is returned. For example:

$echoa*s*d*f
a*s*d*f

Comparisons to other fnmatch/glob implementations

While strict compliance with the existing standards is a worthwhile goal, some discrepancies exist between node-glob and other implementations, and are intentional.

The double-star character**is supported by default, unless thenoglobstarflag is set. This is supported in the manner of bsdglob and bash 5, where**only has special significance if it is the only thing in a path part. That is,a/**/bwill match a/x/y/b,buta/**bwill not.

Note that symlinked directories are not traversed as part of a **,though their contents may match against subsequent portions of the pattern. This prevents infinite loops and duplicates and the like. You can force glob to traverse symlinks with**by setting{follow:true}in the options.

There is no equivalent of thenonulloption. A pattern that does not find any matches simply resolves to nothing. (An empty array, immediately ended stream, etc.)

If brace expansion is not disabled, then it is performed before any other interpretation of the glob pattern. Thus, a pattern like+(a|{b),c)},which would not be valid in bash or zsh, is expandedfirstinto the set of+(a|b)and+(a|c),and those patterns are checked for validity. Since those two are valid, matching proceeds.

The character class patterns[:class:](posix standard named classes) style class patterns are supported and unicode-aware, but[=c=](locale-specific character collation weight), and [.symbol.](collating symbol), are not.

Repeated Slashes

Unlike Bash and zsh, repeated/are always coalesced into a single path separator.

Comments and Negation

Previously, this module let you mark a pattern as a "comment" if it started with a#character, or a "negated" pattern if it started with a!character.

These options were deprecated in version 5, and removed in version 6.

To specify things that should not match, use theignoreoption.

Windows

Please only use forward-slashes in glob expressions.

Though windows uses either/or\as its path separator, only /characters are used by this glob implementation. You must use forward-slashesonlyin glob expressions. Back-slashes will always be interpreted as escape characters, not path separators.

Results from absolute patterns such as/foo/*are mounted onto the root setting usingpath.join.On windows, this will by default result in/foo/*matchingC:\foo\bar.txt.

To automatically coerce all\characters to/in pattern strings,thus making it impossible to escape literal glob characters,you may set thewindowsPathsNoEscapeoption to true.

Windows, CWDs, Drive Letters, and UNC Paths

On posix systems, when a pattern starts with/,anycwd option is ignored, and the traversal starts at/,plus any non-magic path portions specified in the pattern.

On Windows systems, the behavior is similar, but the concept of an "absolute path" is somewhat more involved.

UNC Paths

A UNC path may be used as the start of a pattern on Windows platforms. For example, a pattern like://?/x:/*will return all file entries in the root of thex:drive. A pattern like //ComputerName/Share/*will return all files in the associated share.

UNC path roots are always compared case insensitively.

Drive Letters

A pattern starting with a drive letter, likec:/*,will search in that drive, regardless of anycwdoption provided.

If the pattern starts with/,and is not a UNC path, and there is an explicitcwdoption set with a drive letter, then the drive letter in thecwdis used as the root of the directory traversal.

For example,glob('/tmp', { cwd: 'c:/any/thing' })will return ['c:/tmp']as the result.

If an explicitcwdoption is not provided, and the pattern starts with/,then the traversal will run on the root of the drive provided as thecwdoption. (That is, it is the result of path.resolve('/').)

Race Conditions

Glob searching, by its very nature, is susceptible to race conditions, since it relies on directory walking.

As a result, it is possible that a file that exists when glob looks for it may have been deleted or modified by the time it returns the result.

By design, this implementation caches all readdir calls that it makes, in order to cut down on system overhead. However, this also makes it even more susceptible to races, especially if the cache object is reused between glob calls.

Users are thus advised not to use a glob result as a guarantee of filesystem state in the face of rapid changes. For the vast majority of operations, this is never a problem.

Glob Logo

Glob's logo was created byTanya Brassie.Logo files can be found here.

The logo is licensed under aCreative Commons Attribution-ShareAlike 4.0 International License.

Contributing

Any change to behavior (including bugfixes) must come with a test.

Patches that fail tests or reduce performance will be rejected.

#to run tests
npmtest

#to re-generate test fixtures
npm run test-regen

#run the benchmarks
npm run bench

#to profile javascript
npm run prof

Comparison to Other JavaScript Glob Implementations

tl;dr

If you want glob matching that is as faithful as possible to Bash pattern expansion semantics, and as fast as possible within that constraint,use this module.
If you are reasonably sure that the patterns you will encounter are relatively simple, and want the absolutely fastest glob matcher out there,usefast-glob.
If you are reasonably sure that the patterns you will encounter are relatively simple, and want the convenience of automatically respecting.gitignorefiles,use globby.

There are some other glob matcher libraries on npm, but these three are (in my opinion, as of 2023) the best.

full explanation

Every library reflects a set of opinions and priorities in the trade-offs it makes. Other than this library, I can personally recommend bothglobbyand fast-glob,though they differ in their benefits and drawbacks.

Both have very nice APIs and are reasonably fast.

fast-globis, as far as I am aware, the fastest glob implementation in JavaScript today. However, there are many cases where the choices thatfast-globmakes in pursuit of speed mean that its results differ from the results returned by Bash and other sh-like shells, which may be surprising.

In my testing,fast-globis around 10-20% faster than this module when walking over 200k files nested 4 directories deep1.However, there are some inconsistencies with Bash matching behavior that this module does not suffer from:

**only matches files, not directories
..path portions are not handled unless they appear at the start of the pattern
./!(<pattern>)will not match any files thatstartwith <pattern>,even if they do not match<pattern>.For example,!(9).txtwill not match9999.txt.
Some brace patterns in the middle of a pattern will result in failing to find certain matches.
Extglob patterns are allowed to contain/characters.

Globby exhibits all of the same pattern semantics as fast-glob, (as it is a wrapper around fast-glob) and is slightly slower than node-glob (by about 10-20% in the benchmark test set, or in other words, anywhere from 20-50% slower than fast-glob). However, it adds some API conveniences that may be worth the costs.

Support for.gitignoreand other ignore files.
Support for negated globs (ie, patterns starting with! rather than using a separateignoreoption).

The priority of this module is "correctness" in the sense of performing a glob pattern expansion as faithfully as possible to the behavior of Bash and other sh-like shells, with as much speed as possible.

Note that prior versions ofnode-globarenoton this list. Former versions of this module are far too slow for any cases where performance matters at all, and were designed with APIs that are extremely dated by current JavaScript standards.

[1]: In the cases where this module returns results andfast-globdoesn't, it's even faster, of course.

Benchmark Results

First number is time, smaller is better.

Second number is the count of results returned.

--- pattern: '**' ---
~~ sync ~~
node fast-glob sync 0m0.598s 200364
node globby sync 0m0.765s 200364
node current globSync mjs 0m0.683s 222656
node current glob syncStream 0m0.649s 222656
~~ async ~~
node fast-glob async 0m0.350s 200364
node globby async 0m0.509s 200364
node current glob async mjs 0m0.463s 222656
node current glob stream 0m0.411s 222656

--- pattern: '**/..' ---
~~ sync ~~
node fast-glob sync 0m0.486s 0
node globby sync 0m0.769s 200364
node current globSync mjs 0m0.564s 2242
node current glob syncStream 0m0.583s 2242
~~ async ~~
node fast-glob async 0m0.283s 0
node globby async 0m0.512s 200364
node current glob async mjs 0m0.299s 2242
node current glob stream 0m0.312s 2242

--- pattern: './**/0/**/0/**/0/**/0/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.490s 10
node globby sync 0m0.517s 10
node current globSync mjs 0m0.540s 10
node current glob syncStream 0m0.550s 10
~~ async ~~
node fast-glob async 0m0.290s 10
node globby async 0m0.296s 10
node current glob async mjs 0m0.278s 10
node current glob stream 0m0.302s 10

--- pattern: './**/[01]/**/[12]/**/[23]/**/[45]/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.500s 160
node globby sync 0m0.528s 160
node current globSync mjs 0m0.556s 160
node current glob syncStream 0m0.573s 160
~~ async ~~
node fast-glob async 0m0.283s 160
node globby async 0m0.301s 160
node current glob async mjs 0m0.306s 160
node current glob stream 0m0.322s 160

--- pattern: './**/0/**/0/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.502s 5230
node globby sync 0m0.527s 5230
node current globSync mjs 0m0.544s 5230
node current glob syncStream 0m0.557s 5230
~~ async ~~
node fast-glob async 0m0.285s 5230
node globby async 0m0.305s 5230
node current glob async mjs 0m0.304s 5230
node current glob stream 0m0.310s 5230

--- pattern: '**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.580s 200023
node globby sync 0m0.771s 200023
node current globSync mjs 0m0.685s 200023
node current glob syncStream 0m0.649s 200023
~~ async ~~
node fast-glob async 0m0.349s 200023
node globby async 0m0.509s 200023
node current glob async mjs 0m0.427s 200023
node current glob stream 0m0.388s 200023

--- pattern: '{**/*.txt,**/?/**/*.txt,**/?/**/?/**/*.txt,**/?/**/?/**/?/**/*.txt,**/?/**/?/**/?/**/?/**/*.txt}' ---
~~ sync ~~
node fast-glob sync 0m0.589s 200023
node globby sync 0m0.771s 200023
node current globSync mjs 0m0.716s 200023
node current glob syncStream 0m0.684s 200023
~~ async ~~
node fast-glob async 0m0.351s 200023
node globby async 0m0.518s 200023
node current glob async mjs 0m0.462s 200023
node current glob stream 0m0.468s 200023

--- pattern: '**/5555/0000/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.496s 1000
node globby sync 0m0.519s 1000
node current globSync mjs 0m0.539s 1000
node current glob syncStream 0m0.567s 1000
~~ async ~~
node fast-glob async 0m0.285s 1000
node globby async 0m0.299s 1000
node current glob async mjs 0m0.305s 1000
node current glob stream 0m0.301s 1000

--- pattern: './**/0/**/../[01]/**/0/../**/0/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.484s 0
node globby sync 0m0.507s 0
node current globSync mjs 0m0.577s 4880
node current glob syncStream 0m0.586s 4880
~~ async ~~
node fast-glob async 0m0.280s 0
node globby async 0m0.298s 0
node current glob async mjs 0m0.327s 4880
node current glob stream 0m0.324s 4880

--- pattern: '**/????/????/????/????/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.547s 100000
node globby sync 0m0.673s 100000
node current globSync mjs 0m0.626s 100000
node current glob syncStream 0m0.618s 100000
~~ async ~~
node fast-glob async 0m0.315s 100000
node globby async 0m0.414s 100000
node current glob async mjs 0m0.366s 100000
node current glob stream 0m0.345s 100000

--- pattern: './{**/?{/**/?{/**/?{/**/?,,,,},,,,},,,,},,,}/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.588s 100000
node globby sync 0m0.670s 100000
node current globSync mjs 0m0.717s 200023
node current glob syncStream 0m0.687s 200023
~~ async ~~
node fast-glob async 0m0.343s 100000
node globby async 0m0.418s 100000
node current glob async mjs 0m0.519s 200023
node current glob stream 0m0.451s 200023

--- pattern: '**/!(0|9).txt' ---
~~ sync ~~
node fast-glob sync 0m0.573s 160023
node globby sync 0m0.731s 160023
node current globSync mjs 0m0.680s 180023
node current glob syncStream 0m0.659s 180023
~~ async ~~
node fast-glob async 0m0.345s 160023
node globby async 0m0.476s 160023
node current glob async mjs 0m0.427s 180023
node current glob stream 0m0.388s 180023

--- pattern: './{*/**/../{*/**/../{*/**/../{*/**/../{*/**,,,,},,,,},,,,},,,,},,,,}/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.483s 0
node globby sync 0m0.512s 0
node current globSync mjs 0m0.811s 200023
node current glob syncStream 0m0.773s 200023
~~ async ~~
node fast-glob async 0m0.280s 0
node globby async 0m0.299s 0
node current glob async mjs 0m0.617s 200023
node current glob stream 0m0.568s 200023

--- pattern: './*/**/../*/**/../*/**/../*/**/../*/**/../*/**/../*/**/../*/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.485s 0
node globby sync 0m0.507s 0
node current globSync mjs 0m0.759s 200023
node current glob syncStream 0m0.740s 200023
~~ async ~~
node fast-glob async 0m0.281s 0
node globby async 0m0.297s 0
node current glob async mjs 0m0.544s 200023
node current glob stream 0m0.464s 200023

--- pattern: './*/**/../*/**/../*/**/../*/**/../*/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.486s 0
node globby sync 0m0.513s 0
node current globSync mjs 0m0.734s 200023
node current glob syncStream 0m0.696s 200023
~~ async ~~
node fast-glob async 0m0.286s 0
node globby async 0m0.296s 0
node current glob async mjs 0m0.506s 200023
node current glob stream 0m0.483s 200023

--- pattern: './0/**/../1/**/../2/**/../3/**/../4/**/../5/**/../6/**/../7/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.060s 0
node globby sync 0m0.074s 0
node current globSync mjs 0m0.067s 0
node current glob syncStream 0m0.066s 0
~~ async ~~
node fast-glob async 0m0.060s 0
node globby async 0m0.075s 0
node current glob async mjs 0m0.066s 0
node current glob stream 0m0.067s 0

--- pattern: './**/?/**/?/**/?/**/?/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.568s 100000
node globby sync 0m0.651s 100000
node current globSync mjs 0m0.619s 100000
node current glob syncStream 0m0.617s 100000
~~ async ~~
node fast-glob async 0m0.332s 100000
node globby async 0m0.409s 100000
node current glob async mjs 0m0.372s 100000
node current glob stream 0m0.351s 100000

--- pattern: '**/*/**/*/**/*/**/*/**' ---
~~ sync ~~
node fast-glob sync 0m0.603s 200113
node globby sync 0m0.798s 200113
node current globSync mjs 0m0.730s 222137
node current glob syncStream 0m0.693s 222137
~~ async ~~
node fast-glob async 0m0.356s 200113
node globby async 0m0.525s 200113
node current glob async mjs 0m0.508s 222137
node current glob stream 0m0.455s 222137

--- pattern: './**/*/**/*/**/*/**/*/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.622s 200000
node globby sync 0m0.792s 200000
node current globSync mjs 0m0.722s 200000
node current glob syncStream 0m0.695s 200000
~~ async ~~
node fast-glob async 0m0.369s 200000
node globby async 0m0.527s 200000
node current glob async mjs 0m0.502s 200000
node current glob stream 0m0.481s 200000

--- pattern: '**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.588s 200023
node globby sync 0m0.771s 200023
node current globSync mjs 0m0.684s 200023
node current glob syncStream 0m0.658s 200023
~~ async ~~
node fast-glob async 0m0.352s 200023
node globby async 0m0.516s 200023
node current glob async mjs 0m0.432s 200023
node current glob stream 0m0.384s 200023

--- pattern: './**/**/**/**/**/**/**/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.589s 200023
node globby sync 0m0.766s 200023
node current globSync mjs 0m0.682s 200023
node current glob syncStream 0m0.652s 200023
~~ async ~~
node fast-glob async 0m0.352s 200023
node globby async 0m0.523s 200023
node current glob async mjs 0m0.436s 200023
node current glob stream 0m0.380s 200023

--- pattern: '**/*/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.592s 200023
node globby sync 0m0.776s 200023
node current globSync mjs 0m0.691s 200023
node current glob syncStream 0m0.659s 200023
~~ async ~~
node fast-glob async 0m0.357s 200023
node globby async 0m0.513s 200023
node current glob async mjs 0m0.471s 200023
node current glob stream 0m0.424s 200023

--- pattern: '**/*/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.585s 200023
node globby sync 0m0.766s 200023
node current globSync mjs 0m0.694s 200023
node current glob syncStream 0m0.664s 200023
~~ async ~~
node fast-glob async 0m0.350s 200023
node globby async 0m0.514s 200023
node current glob async mjs 0m0.472s 200023
node current glob stream 0m0.424s 200023

--- pattern: '**/[0-9]/**/*.txt' ---
~~ sync ~~
node fast-glob sync 0m0.544s 100000
node globby sync 0m0.636s 100000
node current globSync mjs 0m0.626s 100000
node current glob syncStream 0m0.621s 100000
~~ async ~~
node fast-glob async 0m0.322s 100000
node globby async 0m0.404s 100000
node current glob async mjs 0m0.360s 100000
node current glob stream 0m0.352s 100000

Name		Name	Last commit message	Last commit date
Latest commit History 722 Commits
.github/workflows		.github/workflows
.tshy		.tshy
examples		examples
logo		logo
scripts		scripts
src		src
tap-snapshots/test		tap-snapshots/test
test		test
.gitignore		.gitignore
.prettierignore		.prettierignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
benchclean.cjs		benchclean.cjs
benchmark.sh		benchmark.sh
changelog.md		changelog.md
fixup.sh		fixup.sh
make-benchmark-fixture.sh		make-benchmark-fixture.sh
oh-my-glob.gif		oh-my-glob.gif
package-lock.json		package-lock.json
package.json		package.json
patterns.sh		patterns.sh
prof.sh		prof.sh
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json

License

isaacs/node-glob

Folders and files

Latest commit

History

Repository files navigation

Glob

Usage

Command Line Interface

glob(pattern: string | string[], options?: GlobOptions) => Promise<string[] | Path[]>

globSync(pattern: string | string[], options?: GlobOptions) => string[] | Path[]

globIterate(pattern: string | string[], options?: GlobOptions) => AsyncGenerator<string>

globIterateSync(pattern: string | string[], options?: GlobOptions) => Generator<string>

globStream(pattern: string | string[], options?: GlobOptions) => Minipass<string | Path>

globStreamSync(pattern: string | string[], options?: GlobOptions) => Minipass<string | Path>

hasMagic(pattern: string | string[], options?: GlobOptions) => boolean

escape(pattern: string, options?: GlobOptions) => string

unescape(pattern: string, options?: GlobOptions) => string

ClassGlob

const g = new Glob(pattern: string | string[], options: GlobOptions)

g.stream()

g.streamSync()

g.iterate()

g.iterateSync()

g.walk()

g.walkSync()