1 # micromatch [![NPM version](https://img.shields.io/npm/v/micromatch.svg?style=flat)](https://www.npmjs.com/package/micromatch) [![NPM downloads](https://img.shields.io/npm/dm/micromatch.svg?style=flat)](https://npmjs.org/package/micromatch) [![Build Status](https://img.shields.io/travis/jonschlinkert/micromatch.svg?style=flat)](https://travis-ci.org/jonschlinkert/micromatch)
3 > Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch.
5 Micromatch supports all of the same matching features as [minimatch](https://github.com/isaacs/minimatch) and [multimatch](https://github.com/sindresorhus/multimatch).
7 * [mm()](#usage) is the same as [multimatch()](https://github.com/sindresorhus/multimatch)
8 * [mm.match()](#match) is the same as [minimatch.match()](https://github.com/isaacs/minimatch)
9 * use [mm.isMatch()](#ismatch) instead of [minimatch()](https://github.com/isaacs/minimatch)
13 Install with [npm](https://www.npmjs.com/):
16 $ npm install --save micromatch
22 var mm = require('micromatch');
30 * [Drop-in replacement](#switch-from-minimatch) for [minimatch](https://github.com/isaacs/minimatch) and [multimatch](https://github.com/sindresorhus/multimatch)
31 * Built-in support for multiple glob patterns, like `['foo/*.js', '!bar.js']`
32 * [Brace Expansion](https://github.com/jonschlinkert/braces) (`foo/bar-{1..5}.md`, `one/{two,three}/four.md`)
33 * Typical glob patterns, like `**/*`, `a/b/*.js`, or `['foo/*.js', '!bar.js']`
34 * Methods like `.isMatch()`, `.contains()` and `.any()`
36 **Extended globbing features:**
38 * Logical `OR` (`foo/bar/(abc|xyz).js`)
39 * Regex character classes (`foo/bar/baz-[1-5].js`)
40 * POSIX [bracket expressions](https://github.com/jonschlinkert/expand-brackets) (`**/[[:alpha:][:digit:]]/`)
41 * [extglobs](https://github.com/jonschlinkert/extglob) (`**/+(x|y)`, `!(a|b)`, etc).
43 You can combine these to create whatever matching patterns you need.
49 mm(['fa', 'fb', 'f', 'fo'], '!(f!(o))');
53 ## Why switch to micromatch?
55 * Native support for multiple glob patterns, no need for wrappers like [multimatch](https://github.com/sindresorhus/multimatch)
56 * [10-55x faster](#benchmarks) and more performant than [minimatch](https://github.com/isaacs/minimatch) and [multimatch](https://github.com/sindresorhus/multimatch). This is achieved through a combination of caching and regex optimization strategies, a fundamentally different approach than minimatch.
57 * More extensive support for the Bash 4.3 specification
58 * More complete extglob support
59 * Extensive [unit tests](./test) (approx. 1,300 tests). Minimatch fails many of the tests.
61 ### Switch from minimatch
63 Use `mm.isMatch()` instead of `minimatch()`:
66 mm.isMatch('foo', 'b*');
70 Use `mm.match()` instead of `minimatch.match()`:
73 mm.match(['foo', 'bar'], 'b*');
77 ### Switch from multimatch
82 mm(['foo', 'bar', 'baz'], ['f*', '*z']);
90 Add micromatch to your node.js project:
93 var mm = require('micromatch');
99 mm(array_of_strings, glob_patterns[, options]);
105 mm(['foo', 'bar', 'baz'], 'b*');
113 Match files with `.js` or `.txt` extensions.
116 mm(['a.js', 'b.md', 'c.txt'], '*.{js,txt}');
117 //=> ['a.js', 'c.txt']
122 Match anything except for files with the `.md` extension.
125 mm(files, '**/*.!(md)');
127 //=> ['a.js', 'c.txt']
130 **Multiple patterns**
132 Match using an array of patterns.
135 mm(['a.md', 'b.js', 'c.txt', 'd.json'], ['*.md', '*.txt']);
136 //=> ['a.md', 'c.txt']
139 **Negation patterns:**
141 Behavior is designed to be what users would expect, based on conventions that are already well-established.
143 * [minimatch](https://github.com/isaacs/minimatch) behavior is used when the pattern is a string, so patterns are **inclusive by default**.
144 * [multimatch](https://github.com/sindresorhus/multimatch) behavior is used when an array of patterns is passed, so patterns are **exclusive by default**.
147 mm(['a.js', 'b.md', 'c.txt'], '!*.{js,txt}');
150 mm(['a.md', 'b.js', 'c.txt', 'd.json'], ['*.*', '!*.{js,txt}']);
151 //=> ['a.md', 'd.json']
159 var mm = require('micromatch');
165 mm.match(array, globString);
168 Return an array of files that match the given glob pattern. Useful if you only need to use a single glob pattern.
173 mm.match(['ab', 'a/b', 'bb', 'b/c'], '?b');
176 mm.match(['ab', 'a/b', 'bb', 'b/c'], '*/b');
183 mm.isMatch(filepath, globString);
186 Returns true if a file path matches the given glob pattern.
191 mm.isMatch('.verb.md', '*.md');
194 mm.isMatch('.verb.md', '*.md', {dot: true});
200 Returns true if any part of a file path matches the given glob pattern. Think of this is "has path" versus "is path".
204 `.isMatch()` would return false for both of the following:
207 mm.contains('a/b/c', 'a/b');
210 mm.contains('a/b/c', 'a/*');
216 Returns a function for matching using the supplied pattern. e.g. create your own "matcher". The advantage of this method is that the pattern can be compiled outside of a loop.
220 Can be any of the following:
229 var isMatch = mm.matcher('*.md');
232 ['a.md', 'b.txt', 'c.md'].forEach(function(fp) {
241 Returns a function that can be passed to `Array#filter()`.
245 * `patterns` **{String|Array}**:
252 var fn = mm.filter('*.md');
253 ['a.js', 'b.txt', 'c.md'].filter(fn);
256 var fn = mm.filter('[a-c]');
257 ['a', 'b', 'c', 'd', 'e'].filter(fn);
261 Array of glob patterns:
264 var arr = [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15];
266 var fn = mm.filter(['{1..10}', '![7-9]', '!{3..4}']);
268 //=> [1, 2, 5, 6, 10]
271 _(Internally this function generates the matching function by using the [matcher](#matcher) method. You can use the [matcher](#matcher) method directly to create your own filter function)_
275 Returns true if a file path matches any of the given patterns.
278 mm.any(filepath, patterns, options);
283 * filepath `{String}`: The file path to test.
284 * patterns `{String|Array}`: One or more glob patterns
285 * options: `{Object}`: options to pass to the `.matcher()` method.
290 mm.any('abc', ['!*z']);
292 mm.any('abc', ['a*', 'z*']);
296 mm.any('abc', ['z*']);
302 Returns an object with a regex-compatible string and tokens.
307 // when `track` is enabled (for debugging), the `history` array is used
308 // to record each mutation to the glob pattern as it's converted to regex
309 { options: { track: false, dot: undefined, makeRe: true, negated: false },
310 pattern: '(.*\\/|^)bar\\/(?:(?!(?:^|\\/)\\.).)*?',
314 { whole: '**/bar/**',
327 original: '**/bar/**',
328 pattern: '**/bar/**',
334 Create a regular expression for matching file paths based on the given pattern:
338 //=> /^(?:(?!\.)(?=.)[^/]*?\.js)$/
345 Normalize slashes in file paths and glob patterns to forward slashes.
349 Default: `undefined` on non-windows, `true` on windows.
353 Match dotfiles. Same behavior as [minimatch](https://github.com/isaacs/minimatch).
361 Unescape slashes in glob patterns. Use cautiously, especially on windows.
370 mm.isMatch('abc', '\\a\\b\\c', {unescape: true});
376 Remove duplicate elements from the result array.
384 Example of using the `unescape` and `nodupes` options together:
387 mm.match(['abc', '\\a\\b\\c'], '\\a\\b\\c', {unescape: true});
390 mm.match(['abc', '\\a\\b\\c'], '\\a\\b\\c', {unescape: true, nodupes: true});
394 ### options.matchBase
396 Allow glob patterns without slashes to match a file path based on its basename. . Same behavior as [minimatch](https://github.com/isaacs/minimatch).
405 mm(['a/b.js', 'a/c.md'], '*.js');
408 mm(['a/b.js', 'a/c.md'], '*.js', {matchBase: true});
414 Don't expand braces in glob patterns. Same behavior as [minimatch](https://github.com/isaacs/minimatch) `nobrace`.
420 See [braces](https://github.com/jonschlinkert/braces) for more information about extended brace expansion.
422 ### options.nobrackets
424 Don't expand POSIX bracket expressions.
430 See [expand-brackets](https://github.com/jonschlinkert/expand-brackets) for more information about extended bracket expressions.
432 ### options.noextglob
434 Don't expand extended globs.
440 See [extglob](https://github.com/jonschlinkert/extglob) for more information about extended globs.
444 Use a case-insensitive regex for matching files. Same behavior as [minimatch](https://github.com/isaacs/minimatch).
452 Disallow negation (`!`) patterns.
460 If `true`, when no matches are found the actual (array-ified) glob pattern is returned instead of an empty array. Same behavior as [minimatch](https://github.com/isaacs/minimatch).
468 Cache the platform (e.g. `win32`) to prevent this from being looked up for every filepath.
478 Micromatch also supports the following.
480 ### Extended globbing
484 Extended globbing, as described by the bash man page:
486 | **pattern** | **regex equivalent** | **description** |
488 | `?(pattern-list)` | `(... | ...)?` | Matches zero or one occurrence of the given patterns |
489 | `*(pattern-list)` | `(... | ...)*` | Matches zero or more occurrences of the given patterns |
490 | `+(pattern-list)` | `(... | ...)+` | Matches one or more occurrences of the given patterns |
491 | `@(pattern-list)` | `(... | ...)` <sup>*</sup> | Matches one of the given patterns |
492 | `!(pattern-list)` | N/A | Matches anything except one of the given patterns |
494 <sup><strong>*</strong></sup> `@` isn't a RegEx character.
496 Powered by [extglob](https://github.com/jonschlinkert/extglob). Visit that library for the full range of options or to report extglob related issues.
498 See [extglob](https://github.com/jonschlinkert/extglob) for more information about extended globs.
502 In simple cases, brace expansion appears to work the same way as the logical `OR` operator. For example, `(a|b)` will achieve the same result as `{a,b}`.
504 Here are some powerful features unique to brace expansion (versus character classes):
506 * range expansion: `a{1..3}b/*.js` expands to: `['a1b/*.js', 'a2b/*.js', 'a3b/*.js']`
507 * nesting: `a{c,{d,e}}b/*.js` expands to: `['acb/*.js', 'adb/*.js', 'aeb/*.js']`
509 Visit [braces](https://github.com/jonschlinkert/braces) to ask questions and create an issue related to brace-expansion, or to see the full range of features and options related to brace expansion.
511 #### regex character classes
513 With the exception of brace expansion (`{a,b}`, `{1..5}`, etc), most of the special characters convert directly to regex, so you can expect them to follow the same rules and produce the same results as regex.
515 For example, given the list: `['a.js', 'b.js', 'c.js', 'd.js', 'E.js']`:
517 * `[ac].js`: matches both `a` and `c`, returning `['a.js', 'c.js']`
518 * `[b-d].js`: matches from `b` to `d`, returning `['b.js', 'c.js', 'd.js']`
519 * `[b-d].js`: matches from `b` to `d`, returning `['b.js', 'c.js', 'd.js']`
520 * `a/[A-Z].js`: matches and uppercase letter, returning `['a/E.md']`
522 Learn about [regex character classes](http://www.regular-expressions.info/charclass.html).
526 Given `['a.js', 'b.js', 'c.js', 'd.js', 'E.js']`:
528 * `(a|c).js`: would match either `a` or `c`, returning `['a.js', 'c.js']`
529 * `(b|d).js`: would match either `b` or `d`, returning `['b.js', 'd.js']`
530 * `(b|[A-Z]).js`: would match either `b` or an uppercase letter, returning `['b.js', 'E.js']`
532 As with regex, parenthese can be nested, so patterns like `((a|b)|c)/b` will work. But it might be easier to achieve your goal using brace expansion.
534 #### POSIX bracket expressions
539 mm.isMatch('a1', '[[:alpha:][:digit:]]');
543 See [expand-brackets](https://github.com/jonschlinkert/expand-brackets) for more information about extended bracket expressions.
549 Whenever possible parsing behavior for patterns is based on globbing specifications in Bash 4.3. Patterns that aren't described by Bash follow wildmatch spec (used by git).
553 Run the [benchmarks](./benchmark):
563 micromatch x 26,420 ops/sec ±0.89% (91 runs sampled)
564 minimatch x 3,507 ops/sec ±0.64% (97 runs sampled)
567 micromatch x 25,315 ops/sec ±0.82% (93 runs sampled)
568 minimatch x 4,398 ops/sec ±0.86% (94 runs sampled)
571 micromatch x 341,254 ops/sec ±0.78% (93 runs sampled)
572 minimatch x 30,197 ops/sec ±1.12% (91 runs sampled)
575 micromatch x 54,649 ops/sec ±0.74% (94 runs sampled)
576 minimatch x 3,095 ops/sec ±0.82% (95 runs sampled)
579 micromatch x 16,719 ops/sec ±0.79% (95 runs sampled)
580 minimatch x 4,348 ops/sec ±0.86% (96 runs sampled)
583 micromatch x 721 ops/sec ±0.77% (94 runs sampled)
584 minimatch x 17.73 ops/sec ±1.08% (50 runs sampled)
587 micromatch x 5,051 ops/sec ±0.87% (97 runs sampled)
588 minimatch x 628 ops/sec ±0.83% (94 runs sampled)
591 micromatch x 51,280 ops/sec ±0.80% (95 runs sampled)
592 minimatch x 1,923 ops/sec ±0.84% (95 runs sampled)
595 micromatch x 22,440 ops/sec ±0.97% (94 runs sampled)
596 minimatch x 2,481 ops/sec ±1.10% (94 runs sampled)
599 micromatch x 722,823 ops/sec ±1.30% (87 runs sampled)
600 minimatch x 52,967 ops/sec ±1.09% (94 runs sampled)
603 micromatch x 243,471 ops/sec ±0.79% (94 runs sampled)
604 minimatch x 11,736 ops/sec ±0.82% (96 runs sampled)
607 micromatch x 190,874 ops/sec ±0.98% (95 runs sampled)
608 minimatch x 21,699 ops/sec ±0.81% (97 runs sampled)
611 micromatch x 496,393 ops/sec ±3.86% (90 runs sampled)
612 minimatch x 53,765 ops/sec ±0.75% (95 runs sampled)
619 Install dev dependencies:
622 $ npm install -d && npm test
630 Statements : 100% (441/441)
631 Branches : 100% (270/270)
632 Functions : 100% (54/54)
633 Lines : 100% (429/429)
638 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
640 Please be sure to run the benchmarks before/after any code changes to judge the impact before you do a PR. thanks!
644 * [braces](https://www.npmjs.com/package/braces): Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces… [more](https://github.com/jonschlinkert/braces) | [homepage](https://github.com/jonschlinkert/braces "Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces specification.")
645 * [expand-brackets](https://www.npmjs.com/package/expand-brackets): Expand POSIX bracket expressions (character classes) in glob patterns. | [homepage](https://github.com/jonschlinkert/expand-brackets "Expand POSIX bracket expressions (character classes) in glob patterns.")
646 * [expand-range](https://www.npmjs.com/package/expand-range): Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. See… [more](https://github.com/jonschlinkert/expand-range) | [homepage](https://github.com/jonschlinkert/expand-range "Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. See the benchmarks. Used by micromatch.")
647 * [extglob](https://www.npmjs.com/package/extglob): Convert extended globs to regex-compatible strings. Add (almost) the expressive power of regular expressions to… [more](https://github.com/jonschlinkert/extglob) | [homepage](https://github.com/jonschlinkert/extglob "Convert extended globs to regex-compatible strings. Add (almost) the expressive power of regular expressions to glob patterns.")
648 * [fill-range](https://www.npmjs.com/package/fill-range): Fill in a range of numbers or letters, optionally passing an increment or multiplier to… [more](https://github.com/jonschlinkert/fill-range) | [homepage](https://github.com/jonschlinkert/fill-range "Fill in a range of numbers or letters, optionally passing an increment or multiplier to use.")
649 * [gulp-micromatch](https://www.npmjs.com/package/gulp-micromatch): Filter vinyl files with glob patterns, string, regexp, array, object or matcher function. micromatch stream. | [homepage](https://github.com/tunnckocore/gulp-micromatch#readme "Filter vinyl files with glob patterns, string, regexp, array, object or matcher function. micromatch stream.")
650 * [is-glob](https://www.npmjs.com/package/is-glob): Returns `true` if the given string looks like a glob pattern or an extglob pattern… [more](https://github.com/jonschlinkert/is-glob) | [homepage](https://github.com/jonschlinkert/is-glob "Returns `true` if the given string looks like a glob pattern or an extglob pattern. This makes it easy to create code that only uses external modules like node-glob when necessary, resulting in much faster code execution and initialization time, and a bet")
651 * [parse-glob](https://www.npmjs.com/package/parse-glob): Parse a glob pattern into an object of tokens. | [homepage](https://github.com/jonschlinkert/parse-glob "Parse a glob pattern into an object of tokens.")
655 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
659 _(This document was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme) (a [verb](https://github.com/verbose/verb) generator), please don't edit the readme directly. Any changes to the readme must be made in [.verb.md](.verb.md).)_
661 To generate the readme and API documentation with [verb](https://github.com/verbose/verb):
664 $ npm install -g verb verb-generate-readme && verb
669 Install dev dependencies:
672 $ npm install -d && npm test
679 * [github/jonschlinkert](https://github.com/jonschlinkert)
680 * [twitter/jonschlinkert](http://twitter.com/jonschlinkert)
684 Copyright © 2016, [Jon Schlinkert](https://github.com/jonschlinkert).
685 Released under the [MIT license](https://github.com/jonschlinkert/micromatch/blob/master/LICENSE).
689 _This file was generated by [verb](https://github.com/verbose/verb), v0.9.0, on July 15, 2016._