minimatch

A minimal matching utility.

This is the matching library used internally by npm.

It works by converting glob expressions into JavaScript RegExp objects.

Important Security Consideration!

[!WARNING]
This library uses JavaScript regular expressions. Please read the following warning carefully, and be thoughtful about what you provide to this library in production systems.

Any library in JavaScript that deals with matching string patterns using regular expressions will be subject to ReDoS if the pattern is generated using untrusted input.

Efforts have been made to mitigate risk as much as is feasible in such a library, providing maximum recursion depths and so forth, but these measures can only ultimately protect against accidents, not malice. A dedicated attacker can always find patterns that cannot be defended against by a bash-compatible glob pattern matching system that uses JavaScript regular expressions.

To be extremely clear:

[!WARNING]
If you create a system where you take user input, and use that input as the source of a Regular Expression pattern, in this or any extant glob matcher in JavaScript, you will be pwned.

A future version of this library may use a different matching algorithm which does not exhibit backtracking problems. If and when that happens, it will likely be a sweeping change, and those improvements will not be backported to legacy versions.

In the near term, it is not reasonable to continue to play whack-a-mole with security advisories, and so any future ReDoS reports will be considered "working as intended", and resolved entirely by this warning.

Usage

// hybrid module, load with require() or import
import { minimatch } from 'minimatch'
// or:
const { minimatch } = require('minimatch')

minimatch('bar.foo', '*.foo') // true!
minimatch('bar.foo', '*.bar') // false!
minimatch('bar.foo', '*.+(bar|foo)', { debug: true }) // true, and noisy!

Features

Supports these glob features:

• Brace Expansion
• Extended glob matching
• "Globstar" ** matching
• Posix character classes, like [[:alpha:]], supporting the full range of Unicode characters. For example, [[:alpha:]] will match against 'é', though [a-zA-Z] will not. Collating symbol and set matching is not supported, so [[=e=]] will not match 'é' and [[.ch.]] will not match 'ch' in locales where ch is considered a single character.

See:

• man sh
• man bash Pattern Matching
• man 3 fnmatch
• man 5 gitignore

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 in patterns will always be interpreted as escape characters, not path separators.

Note that \ or / will be interpreted as path separators in paths on Windows, and will match against / in glob expressions.

So just always use / in patterns.

UNC Paths

On Windows, UNC paths like //?/c:/... or //ComputerName/Share/... are handled specially.

• Patterns starting with a double-slash followed by some non-slash characters will preserve their double-slash. As a result, a pattern like //* will match //x, but not /x.
• Patterns staring with //?/<drive letter>: will not treat the ? as a wildcard character. Instead, it will be treated as a normal string.
• Patterns starting with //?/<drive letter>:/... will match file paths starting with <drive letter>:/..., and vice versa, as if the //?/ was not present. This behavior only is present when the drive letters are a case-insensitive match to one another. The remaining portions of the path/pattern are compared case sensitively, unless nocase:true is set.

Note that specifying a UNC path using \ characters as path separators is always allowed in the file path argument, but only allowed in the pattern argument when windowsPathsNoEscape: true is set in the options.

Minimatch Class

Create a minimatch object by instantiating the minimatch.Minimatch class.

var Minimatch = require('minimatch').Minimatch
var mm = new Minimatch(pattern, options)

Properties

• pattern The original pattern the minimatch object represents.

• options The options supplied to the constructor.

• set A 2-dimensional array of regexp or string expressions. Each row in the array corresponds to a brace-expanded pattern. Each item in the row corresponds to a single path-part. For example, the pattern {a,b/c}/d would expand to a set of patterns like:

    [ [ a, d ]
    , [ b, c, d ] ]
  

  If a portion of the pattern doesn't have any "magic" in it (that is, it's something like "foo" rather than fo*o?), then it will be left as a string rather than converted to a regular expression.

• regexp Created by the makeRe method. A single regular expression expressing the entire pattern. This is useful in cases where you wish to use the pattern somewhat like fnmatch(3) with FNM_PATH enabled.

• negate True if the pattern is negated.

• comment True if the pattern is a comment.

• empty True if the pattern is "".

Methods

• makeRe() Generate the regexp member if necessary, and return it. Will return false if the pattern is invalid.

• match(fname) Return true if the filename matches the pattern, or false otherwise.

• matchOne(fileArray, patternArray, partial) Take a /-split filename, and match it against a single row in the regExpSet. This method is mainly for internal use, but is exposed so that it can be used by a glob-walker that needs to avoid excessive filesystem calls.

• hasMagic() Returns true if the parsed pattern contains any magic characters. Returns false if all comparator parts are string literals. If the magicalBraces option is set on the constructor, then it will consider brace expansions which are not otherwise magical to be magic. If not set, then a pattern like a{b,c}d will return false, because neither abd nor acd contain any special glob characters.

  This does not mean that the pattern string can be used as a literal filename, as it may contain magic glob characters that are escaped. For example, the pattern \\* or [*] would not be considered to have magic, as the matching portion parses to the literal string '*' and would match a path named '*', not '\\*' or '[*]'. The minimatch.unescape() method may be used to remove escape characters.

All other methods are internal, and will be called as necessary.

minimatch(path, pattern, options)

Main export. Tests a path against the pattern using the options.

var isJS = minimatch(file, '*.js', { matchBase: true })

minimatch.filter(pattern, options)

Returns a function that tests its supplied argument, suitable for use with Array.filter. Example:

var javascripts = fileList.filter(
  minimatch.filter('*.js', { matchBase: true }),
)

minimatch.escape(pattern, options = {})

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

If the windowsPathsNoEscape option 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 in windowsPathsNoEscape mode) cannot be escaped or unescaped.

minimatch.unescape(pattern, options = {})

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

If the windowsPathsNoEscape option 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 windowsPathsNoEscape mode.

When windowsPathsNoEscape is not set, then both brace escapes and backslash escapes are removed.

Slashes (and backslashes in windowsPathsNoEscape mode) cannot be escaped or unescaped.

minimatch.match(list, pattern, options)

Match against the list of files, in the style of fnmatch or glob. If nothing is matched, and options.nonull is set, then return a list containing the pattern itself.

var javascripts = minimatch.match(fileList, '*.js', { matchBase: true })

minimatch.makeRe(pattern, options)

Make a regular expression object from the pattern.

Options

All options are false by default.

debug

Dump a ton of stuff to stderr.

nobrace

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

noglobstar

Disable ** matching against multiple folder names.

dot

Allow patterns to match filenames starting with a period, even if the pattern does not explicitly have a period in that spot.

Note that by default, a/**/b will not match a/.d/b, unless dot is set.

noext

Disable "extglob" style patterns like +(a|b).

nocase

Perform a case-insensitive match.

nocaseMagicOnly

When used with {nocase: true}, create regular expressions that are case-insensitive, but leave string match portions untouched. Has no effect when used without {nocase: true}.

Useful when some other form of case-insensitive matching is used, or if the original string representation is useful in some other way.

nonull

When a match is not found by minimatch.match, return a list containing the pattern itself if this option is set. When not set, an empty list is returned if there are no matches.

magicalBraces

This only affects the results of the Minimatch.hasMagic method.

If the pattern contains brace expansions, such as `a{b