More complete support for the Bash 4.3 specification than minimatch and multimatch. Micromatch passes all of the spec tests from bash, including some that bash still fails.
Fast & Performant - Loads in about 5ms and performs fast matches.
Glob matching - Using wildcards (* and ?), globstars (**) for nested directories
You can mix and match these features to create whatever patterns you need!
Switching to micromatch
(There is one notable difference between micromatch and minimatch in regards to how backslashes are handled. See the notes about backslashes for more information.)
Returns a matcher function from the given glob pattern and options. The returned function takes a string to match as its only argument and returns true if the string is a match.
Filter the keys of the given object with the given glob pattern and options. Does not attempt to match nested keys. If you need this feature, use glob-object instead.
Params
object{Object}: The object with keys to filter.
patterns{String|Array}: One or more glob patterns to use for matching.
options{Object}: See available options for changing how matches are performed
returns{Object}: Returns an object with only keys that match the given patterns.
If set, then patterns without slashes will be matched against the basename of the path if it contains slashes. For example, a?b would match the path /xyz/123/acb, but not /xyz/acb/123.
bash
boolean
false
Follow bash matching rules more strictly - disallows backslashes as escape characters, and treats single stars as globstars (**).
capture
boolean
undefined
Return regex matches in supporting methods.
contains
boolean
undefined
Allows glob to match any part of the given string(s).
cwd
string
process.cwd()
Current working directory. Used by picomatch.split()
debug
boolean
undefined
Debug regular expressions when an error is thrown.
dot
boolean
false
Match dotfiles. Otherwise dotfiles are ignored unless a . is explicitly defined in the pattern.
expandRange
function
undefined
Custom function for expanding ranges in brace patterns, such as {a..z}. The function receives the range values as two arguments, and it must return a string to be used in the generated regex. It's recommended that returned strings be wrapped in parentheses. This option is overridden by the expandBrace option.
failglob
boolean
false
Similar to the failglob behavior in Bash, throws an error when no matches are found. Based on the bash option of the same name.
fastpaths
boolean
true
To speed up processing, full parsing is skipped for a handful common glob patterns. Disable this behavior by setting this option to false.
flags
boolean
undefined
Regex flags to use in the generated regex. If defined, the nocase option will be overridden.
Custom function for formatting the returned string. This is useful for removing leading slashes, converting Windows paths to Posix paths, etc.
ignore
array|string
undefined
One or more glob patterns for excluding strings that should not be matched from the result.
keepQuotes
boolean
false
Retain quotes in the generated regex, since quotes may also be used as an alternative to backslashes.
literalBrackets
boolean
undefined
When true, brackets in the glob pattern will be escaped so that only literal brackets will be matched.
lookbehinds
boolean
true
Support regex positive and negative lookbehinds. Note that you must be using Node 8.1.10 or higher to enable regex lookbehinds.
matchBase
boolean
false
Alias for basename
maxLength
boolean
65536
Limit the max length of the input string. An error is thrown if the input string is longer than this value.
nobrace
boolean
false
Disable brace matching, so that {a,b} and {1..3} would be treated as literal characters.
nobracket
boolean
undefined
Disable matching with regex brackets.
nocase
boolean
false
Perform case-insensitive matching. Equivalent to the regex i flag. Note that this option is ignored when the flags option is defined.
nodupes
boolean
true
Deprecated, use nounique instead. This option will be removed in a future major release. By default duplicates are removed. Disable uniquification by setting this option to false.
noext
boolean
false
Alias for noextglob
noextglob
boolean
false
Disable support for matching with extglobs (like +(a|b))
noglobstar
boolean
false
Disable support for matching nested directories with globstars (**)
nonegate
boolean
false
Disable support for negating with leading !
noquantifiers
boolean
false
Disable support for regex quantifiers (like a{1,2}) and treat them as brace patterns to be expanded.
Enabled by default, this option enforces bash-like behavior with stars immediately following a bracket expression. Bash bracket expressions are similar to regex character classes, but unlike regex, a star following a bracket expression does not repeat the bracketed characters. Instead, the star is treated the same as any other star.
Custom function for expanding ranges in brace patterns. The fill-range library is ideal for this purpose, or you can use custom code to do whatever you need.
Example
The following example shows how to create a glob that matches a numeric folder name between 01 and 25, with leading zeros.
Custom function for formatting strings before they're matched.
Example
// strip leading './' from stringsconst format = str => str.replace(/^\.\//, '');const isMatch = picomatch('foo/*.js', { format });console.log(isMatch('./foo/bar.js')) //=> true
options.ignore
String or array of glob patterns to match files to ignore.
If true, when no matches are found the actual (arrayified) glob pattern is returned instead of an empty array. Same behavior as minimatch option nonull.
(a|c).js: would match either a or c, returning ['a.js', 'c.js']
(b|d).js: would match either b or d, returning ['b.js', 'd.js']
(b|[A-Z]).js: would match either b or an uppercase letter, returning ['b.js', 'E.js']
As with regex, parens can be nested, so patterns like ((a|b)|c)/b will work. Although brace expansion might be friendlier to use, depending on preference.
POSIX bracket expressions
POSIX brackets are intended to be more user-friendly than regex character classes. This of course is in the eye of the beholder.
Whenever possible matching behavior is based on behavior Bash 4.3, which is mostly consistent with minimatch.
However, it's suprising how many edge cases and rabbit holes there are with glob matching, and since there is no real glob specification, and micromatch is more accurate than both Bash and minimatch, there are cases where best-guesses were made for behavior. In a few cases where Bash had no answers, we used wildmatch (used by git) as a fallback.
Backslashes
There is an important, notable difference between minimatch and micromatch in regards to how backslashes are handled in glob patterns.
Micromatch exclusively and explicitly reserves backslashes for escaping characters in a glob pattern, even on windows, which is consistent with bash behavior. More importantly, unescaping globs can result in unsafe regular expressions.
Minimatch converts all backslashes to forward slashes, which means you can't use backslashes to escape any characters in your glob patterns.
We made this decision for micromatch for a couple of reasons:
Consistency with bash conventions.
Glob patterns are not filepaths. They are a type of regular language that is converted to a JavaScript regular expression. Thus, when forward slashes are defined in a glob pattern, the resulting regular expression will match windows or POSIX path separators just fine.
A note about joining paths to globs
Note that when you pass something like path.join('foo', '*') to micromatch, you are creating a filepath and expecting it to still work as a glob pattern. This causes problems on windows, since the path.sep is \\.
In other words, since \\ is reserved as an escape character in globs, on windows path.join('foo', '*') would result in foo\\*, which tells micromatch to match * as a literal character. This is the same behavior as bash.
To solve this, you might be inspired to do something like 'foo\\*'.replace(/\\/g, '/'), but this causes another, potentially much more serious, problem.
Benchmarks
Running benchmarks
Install dependencies for running benchmarks:
$ cd bench && npm install
Run the benchmarks:
$ npm run bench
Latest results
As of August 23, 2024 (longer bars are better):
# .makeRe star micromatch x 2,232,802 ops/sec ±2.34% (89 runs sampled)) minimatch x 781,018 ops/sec ±6.74% (92 runs sampled))# .makeRe star; dot=true micromatch x 1,863,453 ops/sec ±0.74% (93 runs sampled) minimatch x 723,105 ops/sec ±0.75% (93 runs sampled)# .makeRe globstar micromatch x 1,624,179 ops/sec ±2.22% (91 runs sampled) minimatch x 1,117,230 ops/sec ±2.78% (86 runs sampled))# .makeRe globstars micromatch x 1,658,642 ops/sec ±0.86% (92 runs sampled) minimatch x 741,224 ops/sec ±1.24% (89 runs sampled))# .makeRe with leading star micromatch x 1,525,014 ops/sec ±1.63% (90 runs sampled) minimatch x 561,074 ops/sec ±3.07% (89 runs sampled)# .makeRe - braces micromatch x 172,478 ops/sec ±2.37% (78 runs sampled) minimatch x 96,087 ops/sec ±2.34% (88 runs sampled)))# .makeRe braces - range (expanded) micromatch x 26,973 ops/sec ±0.84% (89 runs sampled) minimatch x 3,023 ops/sec ±0.99% (90 runs sampled))# .makeRe braces - range (compiled) micromatch x 152,892 ops/sec ±1.67% (83 runs sampled) minimatch x 992 ops/sec ±3.50% (89 runs sampled)d))# .makeRe braces - nested ranges (expanded) micromatch x 15,816 ops/sec ±13.05% (80 runs sampled) minimatch x 2,953 ops/sec ±1.64% (91 runs sampled)# .makeRe braces - nested ranges (compiled) micromatch x 110,881 ops/sec ±1.85% (82 runs sampled) minimatch x 1,008 ops/sec ±1.51% (91 runs sampled)# .makeRe braces - set (compiled) micromatch x 134,930 ops/sec ±3.54% (63 runs sampled)) minimatch x 43,242 ops/sec ±0.60% (93 runs sampled)# .makeRe braces - nested sets (compiled) micromatch x 94,455 ops/sec ±1.74% (69 runs sampled)) minimatch x 27,720 ops/sec ±1.84% (93 runs sampled))
visit the minimatch documentation to cross-check expected behavior in node.js
if all else fails, since there is no real specification for globs we will probably need to discuss expected behavior and decide how to resolve it. which means any detail you can provide to help with this discussion would be greatly appreciated.
Platform issues
It's important to us that micromatch work consistently on all platforms. If you encounter any platform-specific matching or path related issues, please let us know (pull requests are also greatly appreciated).
About
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guide for advice on opening issues, pull requests, and coding standards.
Running Tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm test
Building docs
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command: