1# minimatch 2 3A minimal matching utility. 4 5This is the matching library used internally by npm. 6 7It works by converting glob expressions into JavaScript `RegExp` 8objects. 9 10## Usage 11 12```js 13// hybrid module, load with require() or import 14import { minimatch } from 'minimatch' 15// or: 16const { 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- [Posix character 31 classes](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html), 32 like `[[:alpha:]]`, supporting the full range of Unicode 33 characters. For example, `[[:alpha:]]` will match against 34 `'é'`, though `[a-zA-Z]` will not. Collating symbol and set 35 matching is not supported, so `[[=e=]]` will _not_ match `'é'` 36 and `[[.ch.]]` will not match `'ch'` in locales where `ch` is 37 considered a single character. 38 39See: 40 41- `man sh` 42- `man bash` [Pattern 43 Matching](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html) 44- `man 3 fnmatch` 45- `man 5 gitignore` 46 47## Windows 48 49**Please only use forward-slashes in glob expressions.** 50 51Though windows uses either `/` or `\` as its path separator, only `/` 52characters are used by this glob implementation. You must use 53forward-slashes **only** in glob expressions. Back-slashes in patterns 54will always be interpreted as escape characters, not path separators. 55 56Note that `\` or `/` _will_ be interpreted as path separators in paths on 57Windows, and will match against `/` in glob expressions. 58 59So just always use `/` in patterns. 60 61### UNC Paths 62 63On Windows, UNC paths like `//?/c:/...` or 64`//ComputerName/Share/...` are handled specially. 65 66- Patterns starting with a double-slash followed by some 67 non-slash characters will preserve their double-slash. As a 68 result, a pattern like `//*` will match `//x`, but not `/x`. 69- Patterns staring with `//?/<drive letter>:` will _not_ treat 70 the `?` as a wildcard character. Instead, it will be treated 71 as a normal string. 72- Patterns starting with `//?/<drive letter>:/...` will match 73 file paths starting with `<drive letter>:/...`, and vice versa, 74 as if the `//?/` was not present. This behavior only is 75 present when the drive letters are a case-insensitive match to 76 one another. The remaining portions of the path/pattern are 77 compared case sensitively, unless `nocase:true` is set. 78 79Note that specifying a UNC path using `\` characters as path 80separators is always allowed in the file path argument, but only 81allowed in the pattern argument when `windowsPathsNoEscape: true` 82is set in the options. 83 84## Minimatch Class 85 86Create a minimatch object by instantiating the `minimatch.Minimatch` class. 87 88```javascript 89var Minimatch = require('minimatch').Minimatch 90var mm = new Minimatch(pattern, options) 91``` 92 93### Properties 94 95- `pattern` The original pattern the minimatch object represents. 96- `options` The options supplied to the constructor. 97- `set` A 2-dimensional array of regexp or string expressions. 98 Each row in the 99 array corresponds to a brace-expanded pattern. Each item in the row 100 corresponds to a single path-part. For example, the pattern 101 `{a,b/c}/d` would expand to a set of patterns like: 102 103 [ [ a, d ] 104 , [ b, c, d ] ] 105 106 If a portion of the pattern doesn't have any "magic" in it 107 (that is, it's something like `"foo"` rather than `fo*o?`), then it 108 will be left as a string rather than converted to a regular 109 expression. 110 111- `regexp` Created by the `makeRe` method. A single regular expression 112 expressing the entire pattern. This is useful in cases where you wish 113 to use the pattern somewhat like `fnmatch(3)` with `FNM_PATH` enabled. 114- `negate` True if the pattern is negated. 115- `comment` True if the pattern is a comment. 116- `empty` True if the pattern is `""`. 117 118### Methods 119 120- `makeRe()` Generate the `regexp` member if necessary, and return it. 121 Will return `false` if the pattern is invalid. 122- `match(fname)` Return true if the filename matches the pattern, or 123 false otherwise. 124- `matchOne(fileArray, patternArray, partial)` Take a `/`-split 125 filename, and match it against a single row in the `regExpSet`. This 126 method is mainly for internal use, but is exposed so that it can be 127 used by a glob-walker that needs to avoid excessive filesystem calls. 128- `hasMagic()` Returns true if the parsed pattern contains any 129 magic characters. Returns false if all comparator parts are 130 string literals. If the `magicalBraces` option is set on the 131 constructor, then it will consider brace expansions which are 132 not otherwise magical to be magic. If not set, then a pattern 133 like `a{b,c}d` will return `false`, because neither `abd` nor 134 `acd` contain any special glob characters. 135 136 This does **not** mean that the pattern string can be used as a 137 literal filename, as it may contain magic glob characters that 138 are escaped. For example, the pattern `\\*` or `[*]` would not 139 be considered to have magic, as the matching portion parses to 140 the literal string `'*'` and would match a path named `'*'`, 141 not `'\\*'` or `'[*]'`. The `minimatch.unescape()` method may 142 be used to remove escape characters. 143 144All other methods are internal, and will be called as necessary. 145 146### minimatch(path, pattern, options) 147 148Main export. Tests a path against the pattern using the options. 149 150```javascript 151var isJS = minimatch(file, '*.js', { matchBase: true }) 152``` 153 154### minimatch.filter(pattern, options) 155 156Returns a function that tests its 157supplied argument, suitable for use with `Array.filter`. Example: 158 159```javascript 160var javascripts = fileList.filter(minimatch.filter('*.js', { matchBase: true })) 161``` 162 163### minimatch.escape(pattern, options = {}) 164 165Escape all magic characters in a glob pattern, so that it will 166only ever match literal strings 167 168If the `windowsPathsNoEscape` option is used, then characters are 169escaped by wrapping in `[]`, because a magic character wrapped in 170a character class can only be satisfied by that exact character. 171 172Slashes (and backslashes in `windowsPathsNoEscape` mode) cannot 173be escaped or unescaped. 174 175### minimatch.unescape(pattern, options = {}) 176 177Un-escape a glob string that may contain some escaped characters. 178 179If the `windowsPathsNoEscape` option is used, then square-brace 180escapes are removed, but not backslash escapes. For example, it 181will turn the string `'[*]'` into `*`, but it will not turn 182`'\\*'` into `'*'`, because `\` is a path separator in 183`windowsPathsNoEscape` mode. 184 185When `windowsPathsNoEscape` is not set, then both brace escapes 186and backslash escapes are removed. 187 188Slashes (and backslashes in `windowsPathsNoEscape` mode) cannot 189be escaped or unescaped. 190 191### minimatch.match(list, pattern, options) 192 193Match against the list of 194files, in the style of fnmatch or glob. If nothing is matched, and 195options.nonull is set, then return a list containing the pattern itself. 196 197```javascript 198var javascripts = minimatch.match(fileList, '*.js', { matchBase: true }) 199``` 200 201### minimatch.makeRe(pattern, options) 202 203Make a regular expression object from the pattern. 204 205## Options 206 207All options are `false` by default. 208 209### debug 210 211Dump a ton of stuff to stderr. 212 213### nobrace 214 215Do not expand `{a,b}` and `{1..3}` brace sets. 216 217### noglobstar 218 219Disable `**` matching against multiple folder names. 220 221### dot 222 223Allow patterns to match filenames starting with a period, even if 224the pattern does not explicitly have a period in that spot. 225 226Note that by default, `a/**/b` will **not** match `a/.d/b`, unless `dot` 227is set. 228 229### noext 230 231Disable "extglob" style patterns like `+(a|b)`. 232 233### nocase 234 235Perform a case-insensitive match. 236 237### nocaseMagicOnly 238 239When used with `{nocase: true}`, create regular expressions that 240are case-insensitive, but leave string match portions untouched. 241Has no effect when used without `{nocase: true}` 242 243Useful when some other form of case-insensitive matching is used, 244or if the original string representation is useful in some other 245way. 246 247### nonull 248 249When a match is not found by `minimatch.match`, return a list containing 250the pattern itself if this option is set. When not set, an empty list 251is returned if there are no matches. 252 253### magicalBraces 254 255This only affects the results of the `Minimatch.hasMagic` method. 256 257If the pattern contains brace expansions, such as `a{b,c}d`, but 258no other magic characters, then the `Minimatch.hasMagic()` method 259will return `false` by default. When this option set, it will 260return `true` for brace expansion as well as other magic glob 261characters. 262 263### matchBase 264 265If set, then patterns without slashes will be matched 266against the basename of the path if it contains slashes. For example, 267`a?b` would match the path `/xyz/123/acb`, but not `/xyz/acb/123`. 268 269### nocomment 270 271Suppress the behavior of treating `#` at the start of a pattern as a 272comment. 273 274### nonegate 275 276Suppress the behavior of treating a leading `!` character as negation. 277 278### flipNegate 279 280Returns from negate expressions the same as if they were not negated. 281(Ie, true on a hit, false on a miss.) 282 283### partial 284 285Compare a partial path to a pattern. As long as the parts of the path that 286are present are not contradicted by the pattern, it will be treated as a 287match. This is useful in applications where you're walking through a 288folder structure, and don't yet have the full path, but want to ensure that 289you do not walk down paths that can never be a match. 290 291For example, 292 293```js 294minimatch('/a/b', '/a/*/c/d', { partial: true }) // true, might be /a/b/c/d 295minimatch('/a/b', '/**/d', { partial: true }) // true, might be /a/b/.../d 296minimatch('/x/y/z', '/a/**/z', { partial: true }) // false, because x !== a 297``` 298 299### windowsPathsNoEscape 300 301Use `\\` as a path separator _only_, and _never_ as an escape 302character. If set, all `\\` characters are replaced with `/` in 303the pattern. Note that this makes it **impossible** to match 304against paths containing literal glob pattern characters, but 305allows matching with patterns constructed using `path.join()` and 306`path.resolve()` on Windows platforms, mimicking the (buggy!) 307behavior of earlier versions on Windows. Please use with 308caution, and be mindful of [the caveat about Windows 309paths](#windows). 310 311For legacy reasons, this is also set if 312`options.allowWindowsEscape` is set to the exact value `false`. 313 314### windowsNoMagicRoot 315 316When a pattern starts with a UNC path or drive letter, and in 317`nocase:true` mode, do not convert the root portions of the 318pattern into a case-insensitive regular expression, and instead 319leave them as strings. 320 321This is the default when the platform is `win32` and 322`nocase:true` is set. 323 324### preserveMultipleSlashes 325 326By default, multiple `/` characters (other than the leading `//` 327in a UNC path, see "UNC Paths" above) are treated as a single 328`/`. 329 330That is, a pattern like `a///b` will match the file path `a/b`. 331 332Set `preserveMultipleSlashes: true` to suppress this behavior. 333 334### optimizationLevel 335 336A number indicating the level of optimization that should be done 337to the pattern prior to parsing and using it for matches. 338 339Globstar parts `**` are always converted to `*` when `noglobstar` 340is set, and multiple adjascent `**` parts are converted into a 341single `**` (ie, `a/**/**/b` will be treated as `a/**/b`, as this 342is equivalent in all cases). 343 344- `0` - Make no further changes. In this mode, `.` and `..` are 345 maintained in the pattern, meaning that they must also appear 346 in the same position in the test path string. Eg, a pattern 347 like `a/*/../c` will match the string `a/b/../c` but not the 348 string `a/c`. 349- `1` - (default) Remove cases where a double-dot `..` follows a 350 pattern portion that is not `**`, `.`, `..`, or empty `''`. For 351 example, the pattern `./a/b/../*` is converted to `./a/*`, and 352 so it will match the path string `./a/c`, but not the path 353 string `./a/b/../c`. Dots and empty path portions in the 354 pattern are preserved. 355- `2` (or higher) - Much more aggressive optimizations, suitable 356 for use with file-walking cases: 357 358 - Remove cases where a double-dot `..` follows a pattern 359 portion that is not `**`, `.`, or empty `''`. Remove empty 360 and `.` portions of the pattern, where safe to do so (ie, 361 anywhere other than the last position, the first position, or 362 the second position in a pattern starting with `/`, as this 363 may indicate a UNC path on Windows). 364 - Convert patterns containing `<pre>/**/../<p>/<rest>` into the 365 equivalent `<pre>/{..,**}/<p>/<rest>`, where `<p>` is a 366 a pattern portion other than `.`, `..`, `**`, or empty 367 `''`. 368 - Dedupe patterns where a `**` portion is present in one and 369 omitted in another, and it is not the final path portion, and 370 they are otherwise equivalent. So `{a/**/b,a/b}` becomes 371 `a/**/b`, because `**` matches against an empty path portion. 372 - Dedupe patterns where a `*` portion is present in one, and a 373 non-dot pattern other than `**`, `.`, `..`, or `''` is in the 374 same position in the other. So `a/{*,x}/b` becomes `a/*/b`, 375 because `*` can match against `x`. 376 377 While these optimizations improve the performance of 378 file-walking use cases such as [glob](http://npm.im/glob) (ie, 379 the reason this module exists), there are cases where it will 380 fail to match a literal string that would have been matched in 381 optimization level 1 or 0. 382 383 Specifically, while the `Minimatch.match()` method will 384 optimize the file path string in the same ways, resulting in 385 the same matches, it will fail when tested with the regular 386 expression provided by `Minimatch.makeRe()`, unless the path 387 string is first processed with 388 `minimatch.levelTwoFileOptimize()` or similar. 389 390### platform 391 392When set to `win32`, this will trigger all windows-specific 393behaviors (special handling for UNC paths, and treating `\` as 394separators in file paths for comparison.) 395 396Defaults to the value of `process.platform`. 397 398## Comparisons to other fnmatch/glob implementations 399 400While strict compliance with the existing standards is a 401worthwhile goal, some discrepancies exist between minimatch and 402other implementations. Some are intentional, and some are 403unavoidable. 404 405If the pattern starts with a `!` character, then it is negated. Set the 406`nonegate` flag to suppress this behavior, and treat leading `!` 407characters normally. This is perhaps relevant if you wish to start the 408pattern with a negative extglob pattern like `!(a|B)`. Multiple `!` 409characters at the start of a pattern will negate the pattern multiple 410times. 411 412If a pattern starts with `#`, then it is treated as a comment, and 413will not match anything. Use `\#` to match a literal `#` at the 414start of a line, or set the `nocomment` flag to suppress this behavior. 415 416The double-star character `**` is supported by default, unless the 417`noglobstar` flag is set. This is supported in the manner of bsdglob 418and bash 4.1, where `**` only has special significance if it is the only 419thing in a path part. That is, `a/**/b` will match `a/x/y/b`, but 420`a/**b` will not. 421 422If an escaped pattern has no matches, and the `nonull` flag is set, 423then minimatch.match returns the pattern as-provided, rather than 424interpreting the character escapes. For example, 425`minimatch.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than 426`"*a?"`. This is akin to setting the `nullglob` option in bash, except 427that it does not resolve escaped pattern characters. 428 429If brace expansion is not disabled, then it is performed before any 430other interpretation of the glob pattern. Thus, a pattern like 431`+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded 432**first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are 433checked for validity. Since those two are valid, matching proceeds. 434 435Negated extglob patterns are handled as closely as possible to 436Bash semantics, but there are some cases with negative extglobs 437which are exceedingly difficult to express in a JavaScript 438regular expression. In particular the negated pattern 439`<start>!(<pattern>*|)*` will in bash match anything that does 440not start with `<start><pattern>`. However, 441`<start>!(<pattern>*)*` _will_ match paths starting with 442`<start><pattern>`, because the empty string can match against 443the negated portion. In this library, `<start>!(<pattern>*|)*` 444will _not_ match any pattern starting with `<start>`, due to a 445difference in precisely which patterns are considered "greedy" in 446Regular Expressions vs bash path expansion. This may be fixable, 447but not without incurring some complexity and performance costs, 448and the trade-off seems to not be worth pursuing. 449 450Note that `fnmatch(3)` in libc is an extremely naive string comparison 451matcher, which does not do anything special for slashes. This library is 452designed to be used in glob searching and file walkers, and so it does do 453special things with `/`. Thus, `foo*` will not match `foo/bar` in this 454library, even though it would in `fnmatch(3)`. 455