Fast, minimal glob matcher for node.js. Similar to micromatch, minimatch and multimatch, but complete Bash 4.3 wildcard support only (no support for exglobs, posix brackets or braces)
Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.
This release includes fixes for windows path edge cases and other improvements for stricter adherence to bash spec.
Fixed
More windows path edge cases
Added
Support for bash-like quoted strings for escaping sequences of characters, such as foo/"**"/bar where ** should be matched literally and not evaluated as special characters.
Nanomatch is a fast and accurate glob matcher with full support for standard Bash glob features, including the following "metacharacters": *, **, ? and [...].
Learn more
Getting started: learn how to install and begin using nanomatch
Features: jump to info about supported patterns, and a glob matching reference
Unit tests: visit unit tests. there is no better way to learn a code library than spending time the unit tests. Nanomatch has 36,000 unit tests - go become a glob matching ninja!
How is this different?
Speed and accuracy
Nanomatch uses snapdragon for parsing and compiling globs, which results in:
Granular control over the entire conversion process in a way that is easy to understand, reason about, and customize.
Faster matching, from a combination of optimized glob patterns and (optional) caching.
Much greater accuracy than minimatch. In fact, nanomatch passes all of the spec tests from bash, including some that bash still fails. However, since there is no real specification for globs, if you encounter a pattern that yields unexpected match results after researching previous issues, please let us know.
Basic globbing only
Nanomatch supports basic globbing only, which is limited to *, **, ? and regex-like brackets.
If you need support for the other bash "expansion" types (in addition to the wildcard matching provided by nanomatch), consider using micromatch instead. (micromatch >=3.0.0 uses the nanomatch parser and compiler for basic glob matching)
Add nanomatch to your project using node's require() system:
var nanomatch =require('nanomatch');// the main export is a function that takes an array of strings to match// and a string or array of patterns to use for matchingnanomatch(list, patterns[, options]);
Params
list{String|Array}: List of strings to perform matches against. This is often a list of file paths.
patterns{String|Array}: One or more glob paterns to use for matching.
Backslashes and quotes can be used to escape characters, forcing nanomatch to regard those characters as a literal characters.
Backslashes
Use backslashes to escape single characters. For example, the following pattern would match foo/*/bar exactly:
'foo/\*/bar'
The following pattern would match foo/ followed by a literal *, followed by zero or more of any characters besides /, followed by /bar.
'foo/\**/bar'
Quoted strings
Use single or double quotes to escape sequences of characters. For example, the following patterns would match foo/**/bar exactly:
'foo/"**"/bar''foo/\'**\'/bar'"foo/'**'/bar"
Matching literal quotes
If you need to match quotes literally, you can escape them as well. For example, the following will match foo/"*"/bar, foo/"a"/bar, foo/"b"/bar, or foo/"c"/bar:
'foo/\\"*\\"/bar'
And the following will match foo/'*'/bar, foo/'a'/bar, foo/'b'/bar, or foo/'c'/bar:
Filter the keys of the given object with the given glob pattern and options. Does not attempt to match nested keys. If you need this feature, use glob-object instead.
Params
object{Object}: The object with keys to filter.
patterns{String|Array}: One or more glob patterns to use for matching.
options{Object}: See available options for changing how matches are performed
returns{Object}: Returns an object with only keys that match the given patterns.
Returns a memoized matcher function from the given glob pattern and options. The returned function takes a string to match as its only argument and returns true if the string is a match.
Params
pattern{String}: Glob pattern
options{Object}: See available options for changing how matches are performed.
returns{Function}: Returns a matcher function.
Example
var nm =require('nanomatch');nm.matcher(pattern[, options]);var isMatch =nm.matcher('*.!(*a)');console.log(isMatch('a.a'));//=> falseconsole.log(isMatch('a.b'));//=> true
Enabled by default, this option enforces bash-like behavior with stars immediately following a bracket expression. Bash bracket expressions are similar to regex character classes, but unlike regex, a star following a bracket expression does not repeat the bracketed characters. Instead, the star is treated the same as an other star.
Type: boolean
Default: true
Example
var files = ['abc','ajz'];console.log(nm(files,'[a-c]*'));//=> ['abc', 'ajz']console.log(nm(files,'[a-c]*', {bash:false}));
cache
options.cache
Disable regex and function memoization.
Type: boolean
Default: undefined
dot
options.dot
Match dotfiles. Same behavior as minimatch option dot.
Type: boolean
Default: false
failglob
options.failglob
Similar to the --failglob behavior in Bash, throws an error when no matches are found.
Type: boolean
Default: undefined
ignore
options.ignore
String or array of glob patterns to match files to ignore.
If true, when no matches are found the actual (arrayified) glob pattern is returned instead of an empty array. Same behavior as minimatch option nonull.
Type: boolean
Default: undefined
slash
options.slash
Customize the slash character(s) to use for matching.
Type: string|function
Default: [/\\] (forward slash and backslash)
star
options.star
Customize the star character(s) to use for matching. It's not recommended that you modify this unless you have advanced knowledge of the compiler and matching rules.
Type: string|function
Default: [^/\\]*?
snapdragon
options.snapdragon
Pass your own instance of snapdragon to customize parsers or compilers.
Type: object
Default: undefined
snapdragon
options.sourcemap
Generate a source map by enabling the sourcemap option with the .parse, .compile, or .create methods.
Nanomatch has full support for standard Bash glob features, including the following "metacharacters": *, **, ? and [...].
Here are some examples of how they work:
Pattern
Description
*
Matches any string except for /, leading ., or /. inside a path
**
Matches any string including /, but not a leading . or /. inside a path. More than two stars (e.g. *** is treated the same as one star, and ** loses its special meaning
foo*
Matches any string beginning with foo
*bar*
Matches any string containing bar (beginning, middle or end)
*.min.js
Matches any string ending with .min.js
[abc]*.js
Matches any string beginning with a, b, or c and ending with .js
abc?
Matches abcd or abcz but not abcde
The exceptions noted for * apply to all patterns that contain a *.
Not supported
The following extended-globbing features are not supported:
If you need any of these features consider using micromatch instead.
Bash expansion libs
Nanomatch is part of a suite of libraries aimed at bringing the power and expressiveness of Bash's matching and expansion capabilities to JavaScript, and - as you can see by the benchmarks - without sacrificing speed.
Related library
Matching Type
Example
Description
nanomatch (you are here)
Wildcards
*
Filename expansion, also referred to as globbing and pathname expansion, allows the use of wildcards for matching.
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guide for advice on opening issues, pull requests, and coding standards.
Running Tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm test
Building docs
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command: