3 A minimal matching utility.
5 [![Build Status](https://secure.travis-ci.org/isaacs/minimatch.png)](http://travis-ci.org/isaacs/minimatch)
8 This is the matching library used internally by npm.
10 Eventually, it will replace the C binding in node-glob.
12 It works by converting glob expressions into JavaScript `RegExp`
18 var minimatch = require("minimatch")
20 minimatch("bar.foo", "*.foo") // true!
21 minimatch("bar.foo", "*.bar") // false!
26 Supports these glob features:
29 * Extended glob matching
30 * "Globstar" `**` matching
39 ### Comparisons to other fnmatch/glob implementations
41 While strict compliance with the existing standards is a worthwhile
42 goal, some discrepancies exist between minimatch and other
43 implementations, and are intentional.
45 If the pattern starts with a `!` character, then it is negated. Set the
46 `nonegate` flag to suppress this behavior, and treat leading `!`
47 characters normally. This is perhaps relevant if you wish to start the
48 pattern with a negative extglob pattern like `!(a|B)`. Multiple `!`
49 characters at the start of a pattern will negate the pattern multiple
52 If a pattern starts with `#`, then it is treated as a comment, and
53 will not match anything. Use `\#` to match a literal `#` at the
54 start of a line, or set the `nocomment` flag to suppress this behavior.
56 The double-star character `**` is supported by default, unless the
57 `noglobstar` flag is set. This is supported in the manner of bsdglob
58 and bash 4.1, where `**` only has special significance if it is the only
59 thing in a path part. That is, `a/**/b` will match `a/x/y/b`, but
60 `a/**b` will not. **Note that this is different from the way that `**` is
61 handled by ruby's `Dir` class.**
63 If an escaped pattern has no matches, and the `nonull` flag is set,
64 then minimatch.match returns the pattern as-provided, rather than
65 interpreting the character escapes. For example,
66 `minimatch.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than
67 `"*a?"`. This is akin to setting the `nullglob` option in bash, except
68 that it does not resolve escaped pattern characters.
70 If brace expansion is not disabled, then it is performed before any
71 other interpretation of the glob pattern. Thus, a pattern like
72 `+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded
73 **first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are
74 checked for validity. Since those two are valid, matching proceeds.
79 Create a minimatch object by instanting the `minimatch.Minimatch` class.
82 var Minimatch = require("minimatch").Minimatch
83 var mm = new Minimatch(pattern, options)
88 * `pattern` The original pattern the minimatch object represents.
89 * `options` The options supplied to the constructor.
90 * `set` A 2-dimensional array of regexp or string expressions.
92 array corresponds to a brace-expanded pattern. Each item in the row
93 corresponds to a single path-part. For example, the pattern
94 `{a,b/c}/d` would expand to a set of patterns like:
99 If a portion of the pattern doesn't have any "magic" in it
100 (that is, it's something like `"foo"` rather than `fo*o?`), then it
101 will be left as a string rather than converted to a regular
104 * `regexp` Created by the `makeRe` method. A single regular expression
105 expressing the entire pattern. This is useful in cases where you wish
106 to use the pattern somewhat like `fnmatch(3)` with `FNM_PATH` enabled.
107 * `negate` True if the pattern is negated.
108 * `comment` True if the pattern is a comment.
109 * `empty` True if the pattern is `""`.
113 * `makeRe` Generate the `regexp` member if necessary, and return it.
114 Will return `false` if the pattern is invalid.
115 * `match(fname)` Return true if the filename matches the pattern, or
117 * `matchOne(fileArray, patternArray, partial)` Take a `/`-split
118 filename, and match it against a single row in the `regExpSet`. This
119 method is mainly for internal use, but is exposed so that it can be
120 used by a glob-walker that needs to avoid excessive filesystem calls.
122 All other methods are internal, and will be called as necessary.
126 The top-level exported function has a `cache` property, which is an LRU
127 cache set to store 100 items. So, calling these methods repeatedly
128 with the same pattern and options will use the same Minimatch object,
129 saving the cost of parsing it multiple times.
131 ### minimatch(path, pattern, options)
133 Main export. Tests a path against the pattern using the options.
136 var isJS = minimatch(file, "*.js", { matchBase: true })
139 ### minimatch.filter(pattern, options)
141 Returns a function that tests its
142 supplied argument, suitable for use with `Array.filter`. Example:
145 var javascripts = fileList.filter(minimatch.filter("*.js", {matchBase: true}))
148 ### minimatch.match(list, pattern, options)
150 Match against the list of
151 files, in the style of fnmatch or glob. If nothing is matched, and
152 options.nonull is set, then return a list containing the pattern itself.
155 var javascripts = minimatch.match(fileList, "*.js", {matchBase: true}))
158 ### minimatch.makeRe(pattern, options)
160 Make a regular expression object from the pattern.
164 All options are `false` by default.
168 Dump a ton of stuff to stderr.
172 Do not expand `{a,b}` and `{1..3}` brace sets.
176 Disable `**` matching against multiple folder names.
180 Allow patterns to match filenames starting with a period, even if
181 the pattern does not explicitly have a period in that spot.
183 Note that by default, `a/**/b` will **not** match `a/.d/b`, unless `dot`
188 Disable "extglob" style patterns like `+(a|b)`.
192 Perform a case-insensitive match.
196 When a match is not found by `minimatch.match`, return a list containing
197 the pattern itself. When set, an empty list is returned if there are
202 If set, then patterns without slashes will be matched
203 against the basename of the path if it contains slashes. For example,
204 `a?b` would match the path `/xyz/123/acb`, but not `/xyz/acb/123`.
208 Suppress the behavior of treating `#` at the start of a pattern as a
213 Suppress the behavior of treating a leading `!` character as negation.
217 Returns from negate expressions the same as if they were not negated.
218 (Ie, true on a hit, false on a miss.)