minimatch

You can use the main minimatch function to test if a specific path matches a glob pattern. It supports both CommonJS (require) and ESM (import) syntax.

import { minimatch } from 'minimatch'
// or:
const { minimatch } = require('minimatch')

minimatch('bar.foo', '*.foo') // true
minimatch('bar.foo', '*.bar') // false

import { minimatch } from 'minimatch'

minimatch('bar.foo', '*.foo') // true!

When working with Windows paths, follow these rules to ensure correct matching:

1. Use forward-slashes in patterns: Always use / in your glob expressions. Backslashes (\) in patterns are interpreted as escape characters, not path separators.
2. UNC Paths:
   • Patterns starting with //?/<drive letter>: treat the ? as a literal string, not a wildcard.
   • Patterns starting with //?/<drive letter>:/... match file paths starting with <drive letter>:/... (case-insensitively for the drive letter).
3. Backslash support: To allow backslashes in the pattern argument as path separators, you must set the windowsPathsNoEscape: true option.

⚠️ Important Security Consideration

minimatch uses JavaScript regular expressions to perform matching. If you use untrusted user input to generate a glob pattern, your system may be vulnerable to Regular expression Denial of Service (ReDoS) attacks.

Do not use user-provided input as the source of a pattern in a production system.

Future versions of the library may implement a non-backtracking algorithm, but such changes will be breaking and will not be backported to legacy versions.

The partial: true option allows you to check if a current path segment could potentially match a full pattern. This is useful when walking a file system to avoid entering directories that cannot satisfy a pattern.

// Returns true, because /a/b might be part of /a/b/c/d
minimatch('/a/b', '/a/*/c/d', { partial: true }) 

// Returns true, because /a/b might be part of /a/b/.../d
minimatch('/a/b', '/**/d', { partial: true }) 

// Returns false, because x !== a
minimatch('/x/y/z', '/a/**/z', { partial: true }) 

minimatch('/a/b', '/a/*/c/d', { partial: true }) // true, might be /a/b/c/d
minimatch('/a/b', '/**/d', { partial: true }) // true, might be /a/b/.../d
minimatch('/x/y/z', '/a/**/z', { partial: true }) // false, because x !== a

The minimatch.filter method returns a predicate function that can be passed directly to Array.prototype.filter to extract files matching a pattern.

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

Use minimatch.match(list, pattern, options) to return an array of all items from a list that match the provided pattern. If no matches are found and the nonull option is set, it returns a list containing the pattern itself.

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

Use minimatch.unescape(pattern, options) to remove escape characters from a glob string.

• Default behavior: Removes both brace escapes and backslash escapes.
• With windowsPathsNoEscape: true: Removes square-brace escapes (e.g., [*] becomes *) but does not remove backslash escapes, as \ is treated as a path separator.

For more complex usage, you can instantiate the Minimatch class. This allows you to inspect properties like set (the expanded pattern parts) or regexp (the generated regular expression).

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

Minimatch has specific behaviors that differ from standard fnmatch or shell implementations:

• Negation: A leading ! negates the pattern. Use nonegate: true to treat ! as a literal.
• Comments: A leading # is treated as a comment. Use nocomment: true or escape it (\#) to match a literal #.
• Globstar (**): Only has special significance if it is the only thing in a path part. a/**/b matches a/x/y/b, but a/**b does not.
• Slash Handling: Unlike fnmatch(3), minimatch treats / specially. foo* will not match foo/bar.
• Brace Expansion: Performed before other interpretations. Patterns like +(a|{b),c)} are expanded first and then validated.