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