nanomatch

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 :heart: and support.

Table of Contents

<details> <summary><strong>Details</strong></summary>

• Install
• What is nanomatch?
• Getting started
  • Installing nanomatch
  • Usage
• Documentation
  • Escaping
• API
• Options
  • options.basename
  • options.bash
  • options.cache
  • options.dot
  • options.failglob
  • options.ignore
  • options.matchBase
  • options.nocase
  • options.nodupes
  • options.noglobstar
  • options.nonegate
  • options.nonull
  • options.nullglob
  • options.slash
  • options.star
  • options.snapdragon
  • options.sourcemap
  • options.unescape
  • options.unixify
• Features
• Bash expansion libs
• Benchmarks
  • Running benchmarks
  • Nanomatch vs. Minimatch vs. Multimatch
• About

</details>

Install

Install with npm:

$ npm install --save nanomatch

<details> <summary><strong>Release history</strong></summary>

History

key

Changelog entries are classified using the following labels (from keep-a-changelog):

• added: for new features
• changed: for changes in existing functionality
• deprecated: for once-stable features removed in upcoming releases
• removed: for deprecated features removed in this release
• fixed: for any bug fixes
• bumped: updated dependencies, only minor or higher will be listed.

1.1.0 - 2017-04-11

Fixed

• adds support for unclosed quotes

Added

• adds support for options.noglobstar

1.0.4 - 2017-04-06

Housekeeping updates. Adds documentation section about escaping, cleans up utils.

1.0.3 - 2017-04-06

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.

1.0.1 - 2016-12-12

Added

• Support for windows path edge cases where backslashes are used in brackets or other unusual combinations.

1.0.0 - 2016-12-12

Stable release.

[0.1.0] - 2016-10-08

First release.

</details>

What is nanomatch?

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
• API documentation: jump to available options and methods
• 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!

<details> <summary><strong>How is this different?</strong></summary>

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)

</details>

Getting started

Installing nanomatch

Install with yarn

$ yarn add nanomatch

Install with npm

$ npm install nanomatch

Usage

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 matching
nanomatch(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.
• options {Object}: Any supported options may be passed

Examples

var nm = require('nanomatch');
console.log(nm(['a', 'b/b', 'c/c/c'], '*'));
//=> ['a']

console.log(nm(['a', 'b/b', 'c/c/c'], '*/*'));
//=> ['b/b']

console.log(nm(['a', 'b/b', 'c/c/c'], '**'));
//=> ['a', 'b/b', 'c/c/c']

See the API documentation for available methods and options.

Documentation

Escaping

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:

'foo/\\\'*\\\'/bar'

API

nanomatch

The main function takes a list of strings and one or more glob patterns to use for matching.

Params

• list {Array}: A list of strings to match
• patterns {String|Array}: One or more glob patterns to use for matching.
• options {Object}: See available options for changing how matches are performed
• returns {Array}: Returns an array of matches

Example

var nm = require('nanomatch');
nm(list, patterns[, options]);

console.log(nm(['a.js', 'a.txt'], ['*.js']));
//=> [ 'a.js' ]

.match

Similar to the main function, but pattern must be a string.

Params

• list {Array}: Array of strings to match
• pattern {String}: Glob pattern to use for matching.
• options {Object}: See available options for changing how matches are performed
• returns {Array}: Returns an array of matches

Example

var nm = require('nanomatch');
nm.match(list, pattern[, options]);

console.log(nm.match(['a.a', 'a.aa', 'a.b', 'a.c'], '*.a'));
//=> ['a.a', 'a.aa']

.isMatch

Returns true if the specified string matches the given glob pattern.

Params

• string {String}: String to match
• pattern {String}: Glob pattern to use for matching.
• options {Object}: See available options for changing how matches are performed
• returns {Boolean}: Returns true if the string matches the glob pattern.

Example

var nm = require('nanomatch');
nm.isMatch(string, pattern[, options]);

console.log(nm.isMatch('a.a', '*.a'));
//=> true
console.log(nm.isMatch('a.b', '*.a'));
//=> false

.some

Retu