name: minimatch
description: Use minimatch (glob pattern matching library) for file path matching, such as *.js, **/*.ts and other glob patterns. Note: Do NOT use user input as pattern source to prevent ReDoS attacks.

minimatch

The glob matching library used internally by npm, converting glob expressions to JavaScript RegExp. Current version 10.x, ESM/CJS dual mode.

Trigger Scenarios

Use when the user needs glob matching, file pattern matching, or .gitignore-style matching.

Installation

npm install minimatch

Basic Usage

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 + stderr debug output

Supported Glob Features

• Brace Expansion — {a,b}, {1..3}
• Extended glob — +(a|b), *(a|b), ?(a|b), @(a|b), !(a|b)
• Globstar — ** matches any number of directory levels
• Posix character classes — [[:alpha:]] (full Unicode support, e.g., é)

Exported APIs

minimatch(path, pattern, options?)

Test whether a path matches a pattern:

minimatch('src/app.js', '*.js', { matchBase: true }); // true

minimatch.filter(pattern, options?)

Returns a filter function that can be passed to Array.filter:

const jsFiles = fileList.filter(minimatch.filter('*.js', { matchBase: true }));

minimatch.match(list, pattern, options?)

Performs fnmatch/glob style matching on a list of files. Returns the pattern itself when no matches are found and nonull: true:

minimatch.match(fileList, '*.js', { matchBase: true });

minimatch.escape(pattern)

Escapes all special characters in a glob pattern so it will match literal text only:

minimatch.escape('*.js'); // '\*.js'

minimatch.unescape(pattern)

Unescapes a pattern:

minimatch.unescape('\\*.js'); // '*.js'

minimatch.makeRe(pattern, options?)

Generates a RegExp object from a pattern:

const re = minimatch.makeRe('*.js');
re.test('foo.js'); // true

Minimatch Class

import { Minimatch } from 'minimatch';
const mm = new Minimatch('**/*.js', { dot: true });

mm.match('src/foo.js');      // true
mm.match('.hidden.js');      // true (because dot: true)
mm.hasMagic();                // true
mm.makeRe();                  // Returns RegExp
mm.negate;                    // false — whether it's a negated ! pattern
mm.comment;                   // false — whether it's a # comment pattern

mm.matchOne(fileArray, patternArray, partial?)

Matches path components after splitting by /, primarily used by glob-walkers to reduce filesystem calls.

All Options (all default to false)

| Option | Description |
|--------|-------------|
| debug | Output debug information to stderr |
| nobrace | Disable {a,b} and {1..3} brace expansion |
| noglobstar | Disable ** multi-level directory matching |
| dot | Allow matching filenames starting with . (disabled by default) |
| noext | Disable extglob patterns such as +(a\|b) |
| nocase | Case-insensitive matching |
| nocaseMagicOnly | Only effective when nocase: true, makes case-insensitive only for parts containing magic characters |
| nonull | When minimatch.match finds no matches, return [pattern] instead of [] |
| magicalBraces | Affects hasMagic(): treats braces without other magic characters as magic |
| matchBase | Patterns without / match against the path basename |
| nocomment | Disable comment patterns starting with # |
| nonegate | Disable negated ! patterns |
| flipNegate | Reverse the result of negated patterns (return false on match) |
| partial | Partial path matching, used when traversing directory trees to determine if a match is possible |
| windowsPathsNoEscape | On Windows, \ acts only as a path separator, not an escape character |
| windowsNoMagicRoot | On Windows + nocase, do NOT make UNC roots/drive letters case-insensitive |
| preserveMultipleSlashes | Preserve consecutive / (default a///b matches a/b) |
| optimizationLevel | Optimization level 0/1/2 (default 1), see reference documentation |
| platform | Defaults to process.platform, setting to 'win32' triggers Windows behavior |

Security Warning (❗Important)

minimatch uses JavaScript regular expressions. Never pass user input as a pattern to this library —

If you build a system that takes user input and uses it directly as a regex pattern, whether with minimatch or any JS glob matcher, you will be pwned.

Future versions may switch to a non-backtracking matching algorithm, but this will not be backported.

Path Notes

• Use only / in patterns — \ is treated as an escape character
• On Windows, \ in paths is automatically matched against /
• UNC paths (//?/C:/..., //Server/Share/...) receive special handling

Reference Documentation

• Optimization level details → references/optimization.md