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