1 | # minimatch
|
2 |
|
3 | A minimal matching utility.
|
4 |
|
5 | [![Build Status](https://secure.travis-ci.org/isaacs/minimatch.png)](http://travis-ci.org/isaacs/minimatch)
|
6 |
|
7 |
|
8 | This is the matching library used internally by npm.
|
9 |
|
10 | Eventually, it will replace the C binding in node-glob.
|
11 |
|
12 | It works by converting glob expressions into JavaScript `RegExp`
|
13 | objects.
|
14 |
|
15 | ## Usage
|
16 |
|
17 | ```javascript
|
18 | var minimatch = require("minimatch")
|
19 |
|
20 | minimatch("bar.foo", "*.foo") // true!
|
21 | minimatch("bar.foo", "*.bar") // false!
|
22 | minimatch("bar.foo", "*.+(bar|foo)", { debug: true }) // true, and noisy!
|
23 | ```
|
24 |
|
25 | ## Features
|
26 |
|
27 | Supports these glob features:
|
28 |
|
29 | * Brace Expansion
|
30 | * Extended glob matching
|
31 | * "Globstar" `**` matching
|
32 |
|
33 | See:
|
34 |
|
35 | * `man sh`
|
36 | * `man bash`
|
37 | * `man 3 fnmatch`
|
38 | * `man 5 gitignore`
|
39 |
|
40 | ## Minimatch Class
|
41 |
|
42 | Create a minimatch object by instanting the `minimatch.Minimatch` class.
|
43 |
|
44 | ```javascript
|
45 | var Minimatch = require("minimatch").Minimatch
|
46 | var mm = new Minimatch(pattern, options)
|
47 | ```
|
48 |
|
49 | ### Properties
|
50 |
|
51 | * `pattern` The original pattern the minimatch object represents.
|
52 | * `options` The options supplied to the constructor.
|
53 | * `set` A 2-dimensional array of regexp or string expressions.
|
54 | Each row in the
|
55 | array corresponds to a brace-expanded pattern. Each item in the row
|
56 | corresponds to a single path-part. For example, the pattern
|
57 | `{a,b/c}/d` would expand to a set of patterns like:
|
58 |
|
59 | [ [ a, d ]
|
60 | , [ b, c, d ] ]
|
61 |
|
62 | If a portion of the pattern doesn't have any "magic" in it
|
63 | (that is, it's something like `"foo"` rather than `fo*o?`), then it
|
64 | will be left as a string rather than converted to a regular
|
65 | expression.
|
66 |
|
67 | * `regexp` Created by the `makeRe` method. A single regular expression
|
68 | expressing the entire pattern. This is useful in cases where you wish
|
69 | to use the pattern somewhat like `fnmatch(3)` with `FNM_PATH` enabled.
|
70 | * `negate` True if the pattern is negated.
|
71 | * `comment` True if the pattern is a comment.
|
72 | * `empty` True if the pattern is `""`.
|
73 |
|
74 | ### Methods
|
75 |
|
76 | * `makeRe` Generate the `regexp` member if necessary, and return it.
|
77 | Will return `false` if the pattern is invalid.
|
78 | * `match(fname)` Return true if the filename matches the pattern, or
|
79 | false otherwise.
|
80 | * `matchOne(fileArray, patternArray, partial)` Take a `/`-split
|
81 | filename, and match it against a single row in the `regExpSet`. This
|
82 | method is mainly for internal use, but is exposed so that it can be
|
83 | used by a glob-walker that needs to avoid excessive filesystem calls.
|
84 |
|
85 | All other methods are internal, and will be called as necessary.
|
86 |
|
87 | ## Functions
|
88 |
|
89 | The top-level exported function has a `cache` property, which is an LRU
|
90 | cache set to store 100 items. So, calling these methods repeatedly
|
91 | with the same pattern and options will use the same Minimatch object,
|
92 | saving the cost of parsing it multiple times.
|
93 |
|
94 | ### minimatch(path, pattern, options)
|
95 |
|
96 | Main export. Tests a path against the pattern using the options.
|
97 |
|
98 | ```javascript
|
99 | var isJS = minimatch(file, "*.js", { matchBase: true })
|
100 | ```
|
101 |
|
102 | ### minimatch.filter(pattern, options)
|
103 |
|
104 | Returns a function that tests its
|
105 | supplied argument, suitable for use with `Array.filter`. Example:
|
106 |
|
107 | ```javascript
|
108 | var javascripts = fileList.filter(minimatch.filter("*.js", {matchBase: true}))
|
109 | ```
|
110 |
|
111 | ### minimatch.match(list, pattern, options)
|
112 |
|
113 | Match against the list of
|
114 | files, in the style of fnmatch or glob. If nothing is matched, and
|
115 | options.nonull is set, then return a list containing the pattern itself.
|
116 |
|
117 | ```javascript
|
118 | var javascripts = minimatch.match(fileList, "*.js", {matchBase: true}))
|
119 | ```
|
120 |
|
121 | ### minimatch.makeRe(pattern, options)
|
122 |
|
123 | Make a regular expression object from the pattern.
|
124 |
|
125 | ## Options
|
126 |
|
127 | All options are `false` by default.
|
128 |
|
129 | ### debug
|
130 |
|
131 | Dump a ton of stuff to stderr.
|
132 |
|
133 | ### nobrace
|
134 |
|
135 | Do not expand `{a,b}` and `{1..3}` brace sets.
|
136 |
|
137 | ### noglobstar
|
138 |
|
139 | Disable `**` matching against multiple folder names.
|
140 |
|
141 | ### dot
|
142 |
|
143 | Allow patterns to match filenames starting with a period, even if
|
144 | the pattern does not explicitly have a period in that spot.
|
145 |
|
146 | Note that by default, `a/**/b` will **not** match `a/.d/b`, unless `dot`
|
147 | is set.
|
148 |
|
149 | ### noext
|
150 |
|
151 | Disable "extglob" style patterns like `+(a|b)`.
|
152 |
|
153 | ### nocase
|
154 |
|
155 | Perform a case-insensitive match.
|
156 |
|
157 | ### nonull
|
158 |
|
159 | When a match is not found by `minimatch.match`, return a list containing
|
160 | the pattern itself. When set, an empty list is returned if there are
|
161 | no matches.
|
162 |
|
163 | ### matchBase
|
164 |
|
165 | If set, then patterns without slashes will be matched
|
166 | against the basename of the path if it contains slashes. For example,
|
167 | `a?b` would match the path `/xyz/123/acb`, but not `/xyz/acb/123`.
|
168 |
|
169 | ### nocomment
|
170 |
|
171 | Suppress the behavior of treating `#` at the start of a pattern as a
|
172 | comment.
|
173 |
|
174 | ### nonegate
|
175 |
|
176 | Suppress the behavior of treating a leading `!` character as negation.
|
177 |
|
178 | ### flipNegate
|
179 |
|
180 | Returns from negate expressions the same as if they were not negated.
|
181 | (Ie, true on a hit, false on a miss.)
|
182 |
|
183 |
|
184 | ## Comparisons to other fnmatch/glob implementations
|
185 |
|
186 | While strict compliance with the existing standards is a worthwhile
|
187 | goal, some discrepancies exist between minimatch and other
|
188 | implementations, and are intentional.
|
189 |
|
190 | If the pattern starts with a `!` character, then it is negated. Set the
|
191 | `nonegate` flag to suppress this behavior, and treat leading `!`
|
192 | characters normally. This is perhaps relevant if you wish to start the
|
193 | pattern with a negative extglob pattern like `!(a|B)`. Multiple `!`
|
194 | characters at the start of a pattern will negate the pattern multiple
|
195 | times.
|
196 |
|
197 | If a pattern starts with `#`, then it is treated as a comment, and
|
198 | will not match anything. Use `\#` to match a literal `#` at the
|
199 | start of a line, or set the `nocomment` flag to suppress this behavior.
|
200 |
|
201 | The double-star character `**` is supported by default, unless the
|
202 | `noglobstar` flag is set. This is supported in the manner of bsdglob
|
203 | and bash 4.1, where `**` only has special significance if it is the only
|
204 | thing in a path part. That is, `a/**/b` will match `a/x/y/b`, but
|
205 | `a/**b` will not.
|
206 |
|
207 | If an escaped pattern has no matches, and the `nonull` flag is set,
|
208 | then minimatch.match returns the pattern as-provided, rather than
|
209 | interpreting the character escapes. For example,
|
210 | `minimatch.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than
|
211 | `"*a?"`. This is akin to setting the `nullglob` option in bash, except
|
212 | that it does not resolve escaped pattern characters.
|
213 |
|
214 | If brace expansion is not disabled, then it is performed before any
|
215 | other interpretation of the glob pattern. Thus, a pattern like
|
216 | `+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded
|
217 | **first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are
|
218 | checked for validity. Since those two are valid, matching proceeds.
|