minimatch

Minimatch is a minimal glob-matching utility that converts shell-style glob expressions into JavaScript RegExp objects, then tests file paths against them. It is the matching library used internally by npm and sits at the foundation of the wider glob ecosystem.

Beyond simple *.js wildcards, minimatch supports brace expansion, extended glob (extglob) patterns, ** globstar matching across directories, POSIX character classes, negation, and a large set of options for case-sensitivity, partial matching, and Windows path handling.

What You Get

• A single minimatch(path, pattern, options) function that returns whether a path matches a glob
• A reusable Minimatch class exposing the parsed set, compiled regexp, and match helpers
• Utility helpers: filter (for Array.filter), match (fnmatch/glob-style list matching), makeRe, escape, and unescape
• Full TypeScript types shipped as a hybrid ESM/CommonJS module
• An extensive option set covering brace expansion, extglobs, globstar, case-insensitivity, partial matching, and Windows path semantics

Common Use Cases

• Filtering lists of file paths against a glob pattern (the core of tools like glob and rimraf)
• Implementing include/exclude rules in build tools, bundlers, linters, and test runners
• Matching .gitignore-style or package.json files-style path patterns
• Reusing a compiled pattern across many paths for performance-sensitive directory walks

Under The Hood

Architecture

Minimatch’s pipeline lives in src/index.ts (the Minimatch class and top-level minimatch function) supported by src/ast.ts, which builds an abstract syntax tree from the pattern. A pattern is first split by / into path parts; braces are expanded via the external brace-expansion dependency into a 2-dimensional set where each row is a brace-expanded variant and each element is a path segment. Each segment is parsed by the AST in ast.ts (handling extglobs, character classes from src/brace-expressions.ts, and globstar) and compiled either to a literal string or a RegExp. Matching walks the split filename against a row via matchOne, with special-casing for ** globstar traversal and Windows UNC/drive-letter roots. src/assert-valid-pattern.ts guards against oversized patterns as a ReDoS mitigation.

Tech Stack

Written in TypeScript targeting Node 18/20/22+, with brace-expansion as its only runtime dependency. It builds via tshy into a hybrid package that ships both ESM and CommonJS entry points with type declarations. Dev tooling includes tap for testing, oxlint for linting, prettier for formatting, and typedoc for API docs.

Code Quality

The repository has an extensive test/ suite (25+ files) covering basics, brace expansion, extglobs, negation, partial matching, Windows path separators, UNC paths, optimization levels, and a dedicated redos.js for regular-expression denial-of-service edge cases, plus tap snapshots. Options are documented inline with JSDoc on the MinimatchOptions interface. The code is dense but well-organized into single-responsibility modules (escape.ts, unescape.ts, brace-expressions.ts, assert-valid-pattern.ts).

API Design

The public API is deliberately small and ergonomic: minimatch('bar.foo', '*.foo') reads naturally, while the Minimatch class exposes lower-level internals (set, regexp, matchOne) for glob-walkers that need to avoid excessive filesystem calls. Every option is a boolean flag with a clear name, and the README documents each one exhaustively. TypeScript types and hybrid module output make it drop-in for both import and require.