455 lines
16 KiB
Markdown
455 lines
16 KiB
Markdown
# minimatch
|
|
|
|
A minimal matching utility.
|
|
|
|
This is the matching library used internally by npm.
|
|
|
|
It works by converting glob expressions into JavaScript `RegExp`
|
|
objects.
|
|
|
|
## Usage
|
|
|
|
```js
|
|
// hybrid module, load with require() or import
|
|
import { minimatch } from 'minimatch'
|
|
// or:
|
|
const { minimatch } = require('minimatch')
|
|
|
|
minimatch('bar.foo', '*.foo') // true!
|
|
minimatch('bar.foo', '*.bar') // false!
|
|
minimatch('bar.foo', '*.+(bar|foo)', { debug: true }) // true, and noisy!
|
|
```
|
|
|
|
## Features
|
|
|
|
Supports these glob features:
|
|
|
|
- Brace Expansion
|
|
- Extended glob matching
|
|
- "Globstar" `**` matching
|
|
- [Posix character
|
|
classes](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html),
|
|
like `[[:alpha:]]`, supporting the full range of Unicode
|
|
characters. For example, `[[:alpha:]]` will match against
|
|
`'é'`, though `[a-zA-Z]` will not. Collating symbol and set
|
|
matching is not supported, so `[[=e=]]` will _not_ match `'é'`
|
|
and `[[.ch.]]` will not match `'ch'` in locales where `ch` is
|
|
considered a single character.
|
|
|
|
See:
|
|
|
|
- `man sh`
|
|
- `man bash` [Pattern
|
|
Matching](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html)
|
|
- `man 3 fnmatch`
|
|
- `man 5 gitignore`
|
|
|
|
## Windows
|
|
|
|
**Please only use forward-slashes in glob expressions.**
|
|
|
|
Though windows uses either `/` or `\` as its path separator, only `/`
|
|
characters are used by this glob implementation. You must use
|
|
forward-slashes **only** in glob expressions. Back-slashes in patterns
|
|
will always be interpreted as escape characters, not path separators.
|
|
|
|
Note that `\` or `/` _will_ be interpreted as path separators in paths on
|
|
Windows, and will match against `/` in glob expressions.
|
|
|
|
So just always use `/` in patterns.
|
|
|
|
### UNC Paths
|
|
|
|
On Windows, UNC paths like `//?/c:/...` or
|
|
`//ComputerName/Share/...` are handled specially.
|
|
|
|
- Patterns starting with a double-slash followed by some
|
|
non-slash characters will preserve their double-slash. As a
|
|
result, a pattern like `//*` will match `//x`, but not `/x`.
|
|
- Patterns staring with `//?/<drive letter>:` will _not_ treat
|
|
the `?` as a wildcard character. Instead, it will be treated
|
|
as a normal string.
|
|
- Patterns starting with `//?/<drive letter>:/...` will match
|
|
file paths starting with `<drive letter>:/...`, and vice versa,
|
|
as if the `//?/` was not present. This behavior only is
|
|
present when the drive letters are a case-insensitive match to
|
|
one another. The remaining portions of the path/pattern are
|
|
compared case sensitively, unless `nocase:true` is set.
|
|
|
|
Note that specifying a UNC path using `\` characters as path
|
|
separators is always allowed in the file path argument, but only
|
|
allowed in the pattern argument when `windowsPathsNoEscape: true`
|
|
is set in the options.
|
|
|
|
## Minimatch Class
|
|
|
|
Create a minimatch object by instantiating the `minimatch.Minimatch` class.
|
|
|
|
```javascript
|
|
var Minimatch = require('minimatch').Minimatch
|
|
var mm = new Minimatch(pattern, options)
|
|
```
|
|
|
|
### Properties
|
|
|
|
- `pattern` The original pattern the minimatch object represents.
|
|
- `options` The options supplied to the constructor.
|
|
- `set` A 2-dimensional array of regexp or string expressions.
|
|
Each row in the
|
|
array corresponds to a brace-expanded pattern. Each item in the row
|
|
corresponds to a single path-part. For example, the pattern
|
|
`{a,b/c}/d` would expand to a set of patterns like:
|
|
|
|
[ [ a, d ]
|
|
, [ b, c, d ] ]
|
|
|
|
If a portion of the pattern doesn't have any "magic" in it
|
|
(that is, it's something like `"foo"` rather than `fo*o?`), then it
|
|
will be left as a string rather than converted to a regular
|
|
expression.
|
|
|
|
- `regexp` Created by the `makeRe` method. A single regular expression
|
|
expressing the entire pattern. This is useful in cases where you wish
|
|
to use the pattern somewhat like `fnmatch(3)` with `FNM_PATH` enabled.
|
|
- `negate` True if the pattern is negated.
|
|
- `comment` True if the pattern is a comment.
|
|
- `empty` True if the pattern is `""`.
|
|
|
|
### Methods
|
|
|
|
- `makeRe()` Generate the `regexp` member if necessary, and return it.
|
|
Will return `false` if the pattern is invalid.
|
|
- `match(fname)` Return true if the filename matches the pattern, or
|
|
false otherwise.
|
|
- `matchOne(fileArray, patternArray, partial)` Take a `/`-split
|
|
filename, and match it against a single row in the `regExpSet`. This
|
|
method is mainly for internal use, but is exposed so that it can be
|
|
used by a glob-walker that needs to avoid excessive filesystem calls.
|
|
- `hasMagic()` Returns true if the parsed pattern contains any
|
|
magic characters. Returns false if all comparator parts are
|
|
string literals. If the `magicalBraces` option is set on the
|
|
constructor, then it will consider brace expansions which are
|
|
not otherwise magical to be magic. If not set, then a pattern
|
|
like `a{b,c}d` will return `false`, because neither `abd` nor
|
|
`acd` contain any special glob characters.
|
|
|
|
This does **not** mean that the pattern string can be used as a
|
|
literal filename, as it may contain magic glob characters that
|
|
are escaped. For example, the pattern `\\*` or `[*]` would not
|
|
be considered to have magic, as the matching portion parses to
|
|
the literal string `'*'` and would match a path named `'*'`,
|
|
not `'\\*'` or `'[*]'`. The `minimatch.unescape()` method may
|
|
be used to remove escape characters.
|
|
|
|
All other methods are internal, and will be called as necessary.
|
|
|
|
### minimatch(path, pattern, options)
|
|
|
|
Main export. Tests a path against the pattern using the options.
|
|
|
|
```javascript
|
|
var isJS = minimatch(file, '*.js', { matchBase: true })
|
|
```
|
|
|
|
### minimatch.filter(pattern, options)
|
|
|
|
Returns a function that tests its
|
|
supplied argument, suitable for use with `Array.filter`. Example:
|
|
|
|
```javascript
|
|
var javascripts = fileList.filter(minimatch.filter('*.js', { matchBase: true }))
|
|
```
|
|
|
|
### minimatch.escape(pattern, options = {})
|
|
|
|
Escape all magic characters in a glob pattern, so that it will
|
|
only ever match literal strings
|
|
|
|
If the `windowsPathsNoEscape` option is used, then characters are
|
|
escaped by wrapping in `[]`, because a magic character wrapped in
|
|
a character class can only be satisfied by that exact character.
|
|
|
|
Slashes (and backslashes in `windowsPathsNoEscape` mode) cannot
|
|
be escaped or unescaped.
|
|
|
|
### minimatch.unescape(pattern, options = {})
|
|
|
|
Un-escape a glob string that may contain some escaped characters.
|
|
|
|
If the `windowsPathsNoEscape` option is used, then square-brace
|
|
escapes are removed, but not backslash escapes. For example, it
|
|
will turn the string `'[*]'` into `*`, but it will not turn
|
|
`'\\*'` into `'*'`, because `\` is a path separator in
|
|
`windowsPathsNoEscape` mode.
|
|
|
|
When `windowsPathsNoEscape` is not set, then both brace escapes
|
|
and backslash escapes are removed.
|
|
|
|
Slashes (and backslashes in `windowsPathsNoEscape` mode) cannot
|
|
be escaped or unescaped.
|
|
|
|
### minimatch.match(list, pattern, options)
|
|
|
|
Match against the list of
|
|
files, in the style of fnmatch or glob. If nothing is matched, and
|
|
options.nonull is set, then return a list containing the pattern itself.
|
|
|
|
```javascript
|
|
var javascripts = minimatch.match(fileList, '*.js', { matchBase: true })
|
|
```
|
|
|
|
### minimatch.makeRe(pattern, options)
|
|
|
|
Make a regular expression object from the pattern.
|
|
|
|
## Options
|
|
|
|
All options are `false` by default.
|
|
|
|
### debug
|
|
|
|
Dump a ton of stuff to stderr.
|
|
|
|
### nobrace
|
|
|
|
Do not expand `{a,b}` and `{1..3}` brace sets.
|
|
|
|
### noglobstar
|
|
|
|
Disable `**` matching against multiple folder names.
|
|
|
|
### dot
|
|
|
|
Allow patterns to match filenames starting with a period, even if
|
|
the pattern does not explicitly have a period in that spot.
|
|
|
|
Note that by default, `a/**/b` will **not** match `a/.d/b`, unless `dot`
|
|
is set.
|
|
|
|
### noext
|
|
|
|
Disable "extglob" style patterns like `+(a|b)`.
|
|
|
|
### nocase
|
|
|
|
Perform a case-insensitive match.
|
|
|
|
### nocaseMagicOnly
|
|
|
|
When used with `{nocase: true}`, create regular expressions that
|
|
are case-insensitive, but leave string match portions untouched.
|
|
Has no effect when used without `{nocase: true}`
|
|
|
|
Useful when some other form of case-insensitive matching is used,
|
|
or if the original string representation is useful in some other
|
|
way.
|
|
|
|
### nonull
|
|
|
|
When a match is not found by `minimatch.match`, return a list containing
|
|
the pattern itself if this option is set. When not set, an empty list
|
|
is returned if there are no matches.
|
|
|
|
### magicalBraces
|
|
|
|
This only affects the results of the `Minimatch.hasMagic` method.
|
|
|
|
If the pattern contains brace expansions, such as `a{b,c}d`, but
|
|
no other magic characters, then the `Minimatch.hasMagic()` method
|
|
will return `false` by default. When this option set, it will
|
|
return `true` for brace expansion as well as other magic glob
|
|
characters.
|
|
|
|
### matchBase
|
|
|
|
If set, then patterns without slashes will be matched
|
|
against the basename of the path if it contains slashes. For example,
|
|
`a?b` would match the path `/xyz/123/acb`, but not `/xyz/acb/123`.
|
|
|
|
### nocomment
|
|
|
|
Suppress the behavior of treating `#` at the start of a pattern as a
|
|
comment.
|
|
|
|
### nonegate
|
|
|
|
Suppress the behavior of treating a leading `!` character as negation.
|
|
|
|
### flipNegate
|
|
|
|
Returns from negate expressions the same as if they were not negated.
|
|
(Ie, true on a hit, false on a miss.)
|
|
|
|
### partial
|
|
|
|
Compare a partial path to a pattern. As long as the parts of the path that
|
|
are present are not contradicted by the pattern, it will be treated as a
|
|
match. This is useful in applications where you're walking through a
|
|
folder structure, and don't yet have the full path, but want to ensure that
|
|
you do not walk down paths that can never be a match.
|
|
|
|
For example,
|
|
|
|
```js
|
|
minimatch('/a/b', '/a/*/c/d', { partial: true }) // true, might be /a/b/c/d
|
|
minimatch('/a/b', '/**/d', { partial: true }) // true, might be /a/b/.../d
|
|
minimatch('/x/y/z', '/a/**/z', { partial: true }) // false, because x !== a
|
|
```
|
|
|
|
### windowsPathsNoEscape
|
|
|
|
Use `\\` as a path separator _only_, and _never_ as an escape
|
|
character. If set, all `\\` characters are replaced with `/` in
|
|
the pattern. Note that this makes it **impossible** to match
|
|
against paths containing literal glob pattern characters, but
|
|
allows matching with patterns constructed using `path.join()` and
|
|
`path.resolve()` on Windows platforms, mimicking the (buggy!)
|
|
behavior of earlier versions on Windows. Please use with
|
|
caution, and be mindful of [the caveat about Windows
|
|
paths](#windows).
|
|
|
|
For legacy reasons, this is also set if
|
|
`options.allowWindowsEscape` is set to the exact value `false`.
|
|
|
|
### windowsNoMagicRoot
|
|
|
|
When a pattern starts with a UNC path or drive letter, and in
|
|
`nocase:true` mode, do not convert the root portions of the
|
|
pattern into a case-insensitive regular expression, and instead
|
|
leave them as strings.
|
|
|
|
This is the default when the platform is `win32` and
|
|
`nocase:true` is set.
|
|
|
|
### preserveMultipleSlashes
|
|
|
|
By default, multiple `/` characters (other than the leading `//`
|
|
in a UNC path, see "UNC Paths" above) are treated as a single
|
|
`/`.
|
|
|
|
That is, a pattern like `a///b` will match the file path `a/b`.
|
|
|
|
Set `preserveMultipleSlashes: true` to suppress this behavior.
|
|
|
|
### optimizationLevel
|
|
|
|
A number indicating the level of optimization that should be done
|
|
to the pattern prior to parsing and using it for matches.
|
|
|
|
Globstar parts `**` are always converted to `*` when `noglobstar`
|
|
is set, and multiple adjascent `**` parts are converted into a
|
|
single `**` (ie, `a/**/**/b` will be treated as `a/**/b`, as this
|
|
is equivalent in all cases).
|
|
|
|
- `0` - Make no further changes. In this mode, `.` and `..` are
|
|
maintained in the pattern, meaning that they must also appear
|
|
in the same position in the test path string. Eg, a pattern
|
|
like `a/*/../c` will match the string `a/b/../c` but not the
|
|
string `a/c`.
|
|
- `1` - (default) Remove cases where a double-dot `..` follows a
|
|
pattern portion that is not `**`, `.`, `..`, or empty `''`. For
|
|
example, the pattern `./a/b/../*` is converted to `./a/*`, and
|
|
so it will match the path string `./a/c`, but not the path
|
|
string `./a/b/../c`. Dots and empty path portions in the
|
|
pattern are preserved.
|
|
- `2` (or higher) - Much more aggressive optimizations, suitable
|
|
for use with file-walking cases:
|
|
|
|
- Remove cases where a double-dot `..` follows a pattern
|
|
portion that is not `**`, `.`, or empty `''`. Remove empty
|
|
and `.` portions of the pattern, where safe to do so (ie,
|
|
anywhere other than the last position, the first position, or
|
|
the second position in a pattern starting with `/`, as this
|
|
may indicate a UNC path on Windows).
|
|
- Convert patterns containing `<pre>/**/../<p>/<rest>` into the
|
|
equivalent `<pre>/{..,**}/<p>/<rest>`, where `<p>` is a
|
|
a pattern portion other than `.`, `..`, `**`, or empty
|
|
`''`.
|
|
- Dedupe patterns where a `**` portion is present in one and
|
|
omitted in another, and it is not the final path portion, and
|
|
they are otherwise equivalent. So `{a/**/b,a/b}` becomes
|
|
`a/**/b`, because `**` matches against an empty path portion.
|
|
- Dedupe patterns where a `*` portion is present in one, and a
|
|
non-dot pattern other than `**`, `.`, `..`, or `''` is in the
|
|
same position in the other. So `a/{*,x}/b` becomes `a/*/b`,
|
|
because `*` can match against `x`.
|
|
|
|
While these optimizations improve the performance of
|
|
file-walking use cases such as [glob](http://npm.im/glob) (ie,
|
|
the reason this module exists), there are cases where it will
|
|
fail to match a literal string that would have been matched in
|
|
optimization level 1 or 0.
|
|
|
|
Specifically, while the `Minimatch.match()` method will
|
|
optimize the file path string in the same ways, resulting in
|
|
the same matches, it will fail when tested with the regular
|
|
expression provided by `Minimatch.makeRe()`, unless the path
|
|
string is first processed with
|
|
`minimatch.levelTwoFileOptimize()` or similar.
|
|
|
|
### platform
|
|
|
|
When set to `win32`, this will trigger all windows-specific
|
|
behaviors (special handling for UNC paths, and treating `\` as
|
|
separators in file paths for comparison.)
|
|
|
|
Defaults to the value of `process.platform`.
|
|
|
|
## Comparisons to other fnmatch/glob implementations
|
|
|
|
While strict compliance with the existing standards is a
|
|
worthwhile goal, some discrepancies exist between minimatch and
|
|
other implementations. Some are intentional, and some are
|
|
unavoidable.
|
|
|
|
If the pattern starts with a `!` character, then it is negated. Set the
|
|
`nonegate` flag to suppress this behavior, and treat leading `!`
|
|
characters normally. This is perhaps relevant if you wish to start the
|
|
pattern with a negative extglob pattern like `!(a|B)`. Multiple `!`
|
|
characters at the start of a pattern will negate the pattern multiple
|
|
times.
|
|
|
|
If a pattern starts with `#`, then it is treated as a comment, and
|
|
will not match anything. Use `\#` to match a literal `#` at the
|
|
start of a line, or set the `nocomment` flag to suppress this behavior.
|
|
|
|
The double-star character `**` is supported by default, unless the
|
|
`noglobstar` flag is set. This is supported in the manner of bsdglob
|
|
and bash 4.1, where `**` only has special significance if it is the only
|
|
thing in a path part. That is, `a/**/b` will match `a/x/y/b`, but
|
|
`a/**b` will not.
|
|
|
|
If an escaped pattern has no matches, and the `nonull` flag is set,
|
|
then minimatch.match returns the pattern as-provided, rather than
|
|
interpreting the character escapes. For example,
|
|
`minimatch.match([], "\\*a\\?")` will return `"\\*a\\?"` rather than
|
|
`"*a?"`. This is akin to setting the `nullglob` option in bash, except
|
|
that it does not resolve escaped pattern characters.
|
|
|
|
If brace expansion is not disabled, then it is performed before any
|
|
other interpretation of the glob pattern. Thus, a pattern like
|
|
`+(a|{b),c)}`, which would not be valid in bash or zsh, is expanded
|
|
**first** into the set of `+(a|b)` and `+(a|c)`, and those patterns are
|
|
checked for validity. Since those two are valid, matching proceeds.
|
|
|
|
Negated extglob patterns are handled as closely as possible to
|
|
Bash semantics, but there are some cases with negative extglobs
|
|
which are exceedingly difficult to express in a JavaScript
|
|
regular expression. In particular the negated pattern
|
|
`<start>!(<pattern>*|)*` will in bash match anything that does
|
|
not start with `<start><pattern>`. However,
|
|
`<start>!(<pattern>*)*` _will_ match paths starting with
|
|
`<start><pattern>`, because the empty string can match against
|
|
the negated portion. In this library, `<start>!(<pattern>*|)*`
|
|
will _not_ match any pattern starting with `<start>`, due to a
|
|
difference in precisely which patterns are considered "greedy" in
|
|
Regular Expressions vs bash path expansion. This may be fixable,
|
|
but not without incurring some complexity and performance costs,
|
|
and the trade-off seems to not be worth pursuing.
|
|
|
|
Note that `fnmatch(3)` in libc is an extremely naive string comparison
|
|
matcher, which does not do anything special for slashes. This library is
|
|
designed to be used in glob searching and file walkers, and so it does do
|
|
special things with `/`. Thus, `foo*` will not match `foo/bar` in this
|
|
library, even though it would in `fnmatch(3)`.
|