glob

What is glob?

The glob npm package allows users to match file paths against specified patterns similar to how shell works. It is widely used for tasks such as file searching, filtering, and bulk operations on sets of files.

What are glob's main functionalities?

File Pattern Matching

Match files using the patterns the shell uses, like stars and stuff.

const glob = require('glob');

glob('**/*.js', function (er, files) {
  // files is an array of filenames.
  // If the `nonull` option is set, and nothing
  // was found, then files is ["**/*.js"]
  // er is an error object or null.
  console.log(files);
});

Synchronous File Pattern Matching

Perform a synchronous glob search.

const glob = require('glob');

const files = glob.sync('**/*.js');
// files is an array of filenames found matching the pattern.
console.log(files);

Pattern Matching with Promises

Use glob with Promises for better async control flow.

const glob = require('glob');
const util = require('util');
const globPromise = util.promisify(glob);

globPromise('**/*.js').then(files => {
  console.log(files);
}).catch(err => {
  console.error('Error occurred:', err);
});

Other packages similar to glob

minimatch

Minimatch is a minimal matching utility that works similarly to glob but focuses on the pattern matching algorithm itself. It is actually used by glob under the hood for its matching capabilities.

fast-glob

Fast-glob is an alternative to glob that claims to be faster due to its use of streams and parallel processing. It provides a similar API and is often used when performance is a critical factor.

micromatch

Micromatch is a smaller, more efficient, and highly configurable globbing library. It provides a powerful and expressive API for pattern matching and is designed to be faster and safer than minimatch.

README

Glob

Match files using the patterns the shell uses, like stars and stuff.

This is a glob implementation in JavaScript. It uses the minimatch library to do its matching.

Usage

var glob = require("glob")

// options is optional
glob("**/*.js", options, function (er, files) {
  // files is an array of filenames.
  // If the `nonull` option is set, and nothing
  // was found, then files is ["**/*.js"]
  // er is an error object or null.
})

Features

Please see the minimatch documentation for more details.

Supports these glob features:

• Brace Expansion
• Extended glob matching
• "Globstar" ** matching

See:

• man sh
• man bash
• man 3 fnmatch
• man 5 gitignore
• minimatch documentation

glob(pattern, [options], cb)

• pattern {String} Pattern to be matched
• options {Object}
• cb {Function}
  • err {Error | null}
  • matches {Array} filenames found matching the pattern

Perform an asynchronous glob search.

glob.sync(pattern, [options])

• pattern {String} Pattern to be matched
• options {Object}
• return: {Array} filenames found matching the pattern

Perform a synchronous glob search.

Class: glob.Glob

Create a Glob object by instanting the glob.Glob class.

var Glob = require("glob").Glob
var mg = new Glob(pattern, options, cb)

It's an EventEmitter, and starts walking the filesystem to find matches immediately.

new glob.Glob(pattern, [options], [cb])

• pattern {String} pattern to search for
• options {Object}
• cb {Function} Called when an error occurs, or matches are found
  • err {Error | null}
  • matches {Array} filenames found matching the pattern

Note that if the sync flag is set in the options, then matches will be immediately available on the g.found member.

Properties

• minimatch The minimatch object that the glob uses.
• options The options object passed in.
• error The error encountered. When an error is encountered, the glob object is in an undefined state, and should be discarded.
• aborted Boolean which is set to true when calling abort(). There is no way at this time to continue a glob search after aborting, but you can re-use the statCache to avoid having to duplicate syscalls.
• statCache Collection of all the stat results the glob search performed.
• cache Convenience object. Each field has the following possible values:
  • false - Path does not exist
  • true - Path exists
  • 1 - Path exists, and is not a directory
  • 2 - Path exists, and is a directory
  • [file, entries, ...] - Path exists, is a directory, and the array value is the results of fs.readdir

Events

• end When the matching is finished, this is emitted with all the matches found. If the nonull option is set, and no match was found, then the matches list contains the original pattern. The matches are sorted, unless the nosort flag is set.
• match Every time a match is found, this is emitted with the matched.
• error Emitted when an unexpected error is encountered, or whenever any fs error occurs if options.strict is set.
• abort When abort() is called, this event is raised.

Methods

• abort Stop the search.

Options

All the options that can be passed to Minimatch can also be passed to Glob to change pattern matching behavior. Also, some have been added, or have glob-specific ramifications.

All options are false by default, unless otherwise noted.

All options are added to the glob object, as well.

• cwd The current working directory in which to search. Defaults to process.cwd().
• root The place where patterns starting with / will be mounted onto. Defaults to path.resolve(options.cwd, "/") (/ on Unix systems, and C:\ or some such on Windows.)
• dot 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.
• nomount By default, a pattern starting with a forward-slash will be "mounted" onto the root setting, so that a valid filesystem path is returned. Set this flag to disable that behavior.
• mark Add a / character to directory matches. Note that this requires additional stat calls.
• nosort Don't sort the results.
• stat Set to true to stat all results. This reduces performance somewhat, and is completely unnecessary, unless readdir is presumed to be an untrustworthy indicator of file existence. It will cause ELOOP to be triggered one level sooner in the case of cyclical symbolic links.
• silent When an unusual error is encountered when attempting to read a directory, a warning will be printed to stderr. Set the silent option to true to suppress these warnings.
• strict When an unusual error is encountered when attempting to read a directory, the process will just continue on in search of other matches. Set the strict option to raise an error in these cases.
• cache See cache property above. Pass in a previously generated cache object to save some fs calls.
• statCache A cache of results of filesystem information, to prevent unnecessary stat calls. While it should not normally be necessary to set this, you may pass the statCache from one glob() call to the options object of another, if you know that the filesystem will not change between calls. (See "Race Conditions" below.)
• sync Perform a synchronous glob search.
• nounique In some cases, brace-expanded patterns can result in the same file showing up multiple times in the result set. By default, this implementation prevents duplicates in the result set. Set this flag to disable that behavior.
• nonull Set to never return an empty set, instead returning a set containing the pattern itself. This is the default in glob(3).
• nocase Perform a case-insensitive match. Note that case-insensitive filesystems will sometimes result in glob returning results that are case-insensitively matched anyway, since readdir and stat will not raise an error.
• debug Set to enable debug logging in minimatch and glob.
• globDebug Set to enable debug logging in glob, but not minimatch.

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.

If the pattern starts with a ! character, then it is negated. Set the nonegate flag to suppress this behavior, and treat leading ! characters normally. This is perhaps relevant if you wish to start the pattern with a negative extglob pattern like !(a|B). Multiple ! characters at the start of a pattern will negate the pattern multiple times.

If a pattern starts with #, then it is treated as a comment, and will not match anything. Use \# to match a literal # at the start of a line, or set the nocomment flag to suppress this behavior.

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

If an escaped pattern has no matches, and the nonull flag is set, then glob returns the pattern as-provided, rather than interpreting the character escapes. For example, glob.match([], "\\*a\\?") will return "\\*a\\?" rather than "*a?". This is akin to setting the nullglob option in bash, except that it does not resolve escaped pattern characters.

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 expanded first into the set of +(a|b) and +(a|c), and those patterns are checked for validity. Since those two are valid, matching proceeds.

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-slashes only in 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 using path.join. On windows, this will by default result in /foo/* matching C:\foo\bar.txt.

Race Conditions

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

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.

As part of its internal implementation, this program caches all stat and 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 or statCache objects are 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.

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
npm test

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

# to benchmark against bash/zsh
npm run bench

# to profile javascript
npm run prof