Glob Pattern Matcher

10.2.5 · active · verified Sun Apr 19

Minimatch is a JavaScript utility library that provides robust glob matching functionality, converting glob expressions into JavaScript `RegExp` objects for efficient pattern matching. It is famously used internally by npm for its file system operations. The current stable version is 10.2.5, with releases typically occurring as needed to address bugs, enhance features, or align with npm's requirements. Key features include support for brace expansion, extended glob matching, globstar (`**`), and Posix character classes (e.g., `[[:alpha:]]`), which are Unicode-aware. A critical aspect of minimatch is its explicit warning regarding Regular Expression Denial of Service (ReDoS) vulnerabilities, advising users to never use untrusted input as glob patterns due to the inherent risks of RegExp-based matching. It also provides specific guidance for Windows users, emphasizing the exclusive use of forward slashes in glob expressions to avoid misinterpretation of backslashes as escape characters.

Common errors

```
RangeError: Maximum call stack size exceeded
```
cause A complex or maliciously crafted glob pattern caused excessive backtracking in the underlying regular expression engine, leading to a ReDoS condition.

fix Review glob pattern sources. If patterns originate from user input, implement strict sanitization or whitelisting. Avoid using complex patterns with untrusted input.
```
Glob pattern with backslashes on Windows does not match expected files.
```
cause On Windows, backslashes (`\`) in glob patterns are interpreted as escape characters, not path separators, causing patterns like `foo\bar` to match `foo\bar` exactly, not `foo/bar`.

fix Ensure all glob patterns consistently use forward slashes (`/`) as path separators, even when running on Windows. Convert any `\` to `/` in the pattern string.
```
TypeError: minimatch is not a function OR TypeError: minimatch is not iterable
```
cause Attempting to use `minimatch` as a default import (e.g., `import minimatch from 'minimatch'`) or without destructuring in CommonJS (e.g., `const minimatch = require('minimatch')`).

fix Use a named import for ESM: `import { minimatch } from 'minimatch'`. For CommonJS, use destructuring: `const { minimatch } = require('minimatch')`.

Warnings

gotcha Glob patterns derived from untrusted user input can lead to Regular Expression Denial of Service (ReDoS) attacks due to the library's reliance on JavaScript regular expressions. This is an inherent risk for any RegExp-based matcher.
Fix: Never use user-provided input directly as a glob pattern without rigorous sanitization or whitelisting. Consider alternative matching strategies for untrusted inputs that do not rely on RegExp.
gotcha On Windows, glob expressions must exclusively use forward slashes ('/') as path separators. Backslashes ('\') will always be interpreted as escape characters within patterns, leading to incorrect matching.
Fix: Always normalize paths to use forward slashes (`/`) before passing them to minimatch as patterns. For example, use `path.posix.normalize(myPath)` or `myPath.replace(/\\/g, '/')` for pattern construction.
breaking This package requires Node.js version 18, 20, or greater than or equal to 22. Older Node.js versions are not supported.
Fix: Upgrade your Node.js runtime to a compatible version (18, 20, or >=22) to use minimatch version 10 and above.
deprecated Future versions of minimatch may introduce a different matching algorithm to mitigate ReDoS. These improvements will NOT be backported to legacy versions. Any future ReDoS reports against older versions will be considered 'working as intended' due to inherent RegExp limitations.
Fix: For the latest ReDoS mitigations (when available), upgrade to the newest major version of minimatch. Be aware that older versions will not receive such security updates.

Install

npm install minimatch npm
yarn add minimatch yarn
pnpm add minimatch pnpm

Imports

minimatch
wrong:
```
import minimatch from 'minimatch'
```
correct:
```
import { minimatch } from 'minimatch'
```
Minimatch is a named export, not a default export.
minimatch (CJS)
wrong:
```
const minimatch = require('minimatch')
```
correct:
```
const { minimatch } = require('minimatch')
```
When using CommonJS require, the `minimatch` function is a named property of the module object, requiring destructuring.
Minimatch class
wrong:
```
import { minimatch } from 'minimatch'; new minimatch(...)
```
correct:
```
import { Minimatch } from 'minimatch'
```
For advanced usage or pre-compiling patterns, the `Minimatch` class can be imported. The class name is capitalized.

Quickstart

Demonstrates basic glob matching, usage with options, and pre-compiling patterns with the `Minimatch` class, including Unicode-aware Posix character classes.

import { minimatch, Minimatch } from 'minimatch';

// Basic usage
console.log(minimatch('foo/bar/baz.js', 'foo/**/baz.js')); // true
console.log(minimatch('foo/bar/file.txt', '*.txt'));       // false (needs path)
console.log(minimatch('file.txt', '*.txt'));               // true

// With options: debug and nobrace
const pattern = 'a/{b,c}/d';
const options = { debug: false, nobrace: false };
console.log(minimatch('a/b/d', pattern, options)); // true
console.log(minimatch('a/c/d', pattern, options)); // true

// Using the Minimatch class for pre-compiled patterns
const mm = new Minimatch('src/**/*.ts', { matchBase: true });
console.log(mm.match('src/components/button.ts')); // true
console.log(mm.match('dist/index.js'));             // false

// Example with Posix character classes (Unicode aware)
console.log(minimatch('é', '[[:alpha:]]')); // true
console.log(minimatch('123', '[[:digit:]]')); // false

view raw JSON →