Main Matching

Core functionality for filtering arrays of strings against glob patterns with support for negation, advanced patterns, and extensive configuration options.

Capabilities

Main Export Function

The primary micromatch function that filters strings from a list using one or more glob patterns.

/**
 * Returns an array of strings that match one or more glob patterns
 * @param {string|string[]} list - List of strings to match
 * @param {string|string[]} patterns - One or more glob patterns to use for matching
 * @param {object} options - See available options for changing how matches are performed
 * @returns {string[]} Returns an array of matches
 */
function micromatch(list, patterns, options);

Usage Examples:

const micromatch = require('micromatch');

// Basic matching
console.log(micromatch(['foo', 'bar', 'baz', 'qux'], ['f*', 'b*']));
//=> ['foo', 'bar', 'baz']

// Negation patterns
console.log(micromatch(['foo', 'bar', 'baz', 'qux'], ['*', '!b*']));
//=> ['foo', 'qux']

// Multiple patterns with options
const files = ['src/app.js', 'test/app.test.js', 'docs/readme.md'];
console.log(micromatch(files, '**/*.js', { dot: true }));
//=> ['src/app.js', 'test/app.test.js']

Match Method (Alias)

Backwards compatibility alias for the main micromatch function.

/**
 * Alias for micromatch() - backwards compatibility
 * @param {string|string[]} list - List of strings to match
 * @param {string|string[]} patterns - One or more glob patterns
 * @param {object} options - See available options
 * @returns {string[]} Returns an array of matches
 */
micromatch.match = micromatch;

Pattern Features

Glob Patterns

Supports standard glob patterns:

• * - Matches any number of characters (except path separators)
• ? - Matches a single character
• [abc] - Matches any character in the set
• [a-z] - Matches any character in the range
• ** - Matches directories recursively (globstar)

Extended Patterns (Extglobs)

When extglobs are enabled (default):

• !(pattern) - Negation
• ?(pattern) - Zero or one occurrence
• +(pattern) - One or more occurrences
• *(pattern) - Zero or more occurrences
• @(pattern) - Exactly one occurrence

Brace Expansion

Supports brace patterns like:

• {a,b,c} - Alternation
• {1..10} - Numeric ranges
• {a..z} - Character ranges

Negation

Leading ! in patterns negates the match:

// Exclude .test.js files
micromatch(files, ['**/*.js', '!**/*.test.js']);

Error Handling

• Throws Error when failglob: true option is set and no matches are found
• Returns empty array [] when no matches found (default behavior)
• Supports nonull and nullglob options for controlling empty result behavior

Performance Notes

• Optimized for performance with fast-path implementations for common patterns
• Lazy compilation of regular expressions
• Efficient handling of large file lists
• Can disable expensive features via options (e.g., noextglob, nobrace)