1# nanomatch [![NPM version](https://img.shields.io/npm/v/nanomatch.svg?style=flat)](https://www.npmjs.com/package/nanomatch) [![NPM monthly downloads](https://img.shields.io/npm/dm/nanomatch.svg?style=flat)](https://npmjs.org/package/nanomatch) [![NPM total downloads](https://img.shields.io/npm/dt/nanomatch.svg?style=flat)](https://npmjs.org/package/nanomatch) [![Linux Build Status](https://img.shields.io/travis/micromatch/nanomatch.svg?style=flat&label=Travis)](https://travis-ci.org/micromatch/nanomatch) [![Windows Build Status](https://img.shields.io/appveyor/ci/micromatch/nanomatch.svg?style=flat&label=AppVeyor)](https://ci.appveyor.com/project/micromatch/nanomatch) 2 3> 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) 4 5Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support. 6 7## Table of Contents 8 9<details> 10<summary><strong>Details</strong></summary> 11 12- [Install](#install) 13- [What is nanomatch?](#what-is-nanomatch) 14- [Getting started](#getting-started) 15 * [Installing nanomatch](#installing-nanomatch) 16 * [Usage](#usage) 17- [Documentation](#documentation) 18 * [Escaping](#escaping) 19- [API](#api) 20- [Options](#options) 21 * [options.basename](#optionsbasename) 22 * [options.bash](#optionsbash) 23 * [options.cache](#optionscache) 24 * [options.dot](#optionsdot) 25 * [options.failglob](#optionsfailglob) 26 * [options.ignore](#optionsignore) 27 * [options.matchBase](#optionsmatchbase) 28 * [options.nocase](#optionsnocase) 29 * [options.nodupes](#optionsnodupes) 30 * [options.noglobstar](#optionsnoglobstar) 31 * [options.nonegate](#optionsnonegate) 32 * [options.nonull](#optionsnonull) 33 * [options.nullglob](#optionsnullglob) 34 * [options.slash](#optionsslash) 35 * [options.star](#optionsstar) 36 * [options.snapdragon](#optionssnapdragon) 37 * [options.sourcemap](#optionssourcemap) 38 * [options.unescape](#optionsunescape) 39 * [options.unixify](#optionsunixify) 40- [Features](#features) 41- [Bash expansion libs](#bash-expansion-libs) 42- [Benchmarks](#benchmarks) 43 * [Running benchmarks](#running-benchmarks) 44 * [Nanomatch vs. Minimatch vs. Multimatch](#nanomatch-vs-minimatch-vs-multimatch) 45- [About](#about) 46 47</details> 48 49## Install 50 51Install with [npm](https://www.npmjs.com/): 52 53```sh 54$ npm install --save nanomatch 55``` 56 57<details> 58<summary><strong>Release history</strong></summary> 59 60## History 61 62### key 63 64Changelog entries are classified using the following labels _(from [keep-a-changelog](https://github.com/olivierlacan/keep-a-changelog)_): 65 66* `added`: for new features 67* `changed`: for changes in existing functionality 68* `deprecated`: for once-stable features removed in upcoming releases 69* `removed`: for deprecated features removed in this release 70* `fixed`: for any bug fixes 71* `bumped`: updated dependencies, only minor or higher will be listed. 72 73### [1.1.0](https://github.com/micromatch/nanomatch/compare/1.0.4...1.1.0) - 2017-04-11 74 75**Fixed** 76 77* adds support for unclosed quotes 78 79**Added** 80 81* adds support for `options.noglobstar` 82 83### [1.0.4](https://github.com/micromatch/nanomatch/compare/1.0.3...1.0.4) - 2017-04-06 84 85Housekeeping updates. Adds documentation section about escaping, cleans up utils. 86 87### [1.0.3](https://github.com/micromatch/nanomatch/compare/1.0.1...1.0.3) - 2017-04-06 88 89This release includes fixes for windows path edge cases and other improvements for stricter adherence to bash spec. 90 91**Fixed** 92 93* More windows path edge cases 94 95**Added** 96 97* 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. 98 99### [1.0.1](https://github.com/micromatch/nanomatch/compare/1.0.0...1.0.1) - 2016-12-12 100 101**Added** 102 103* Support for windows path edge cases where backslashes are used in brackets or other unusual combinations. 104 105### [1.0.0](https://github.com/micromatch/nanomatch/compare/0.1.0...1.0.0) - 2016-12-12 106 107Stable release. 108 109### [0.1.0] - 2016-10-08 110 111First release. 112 113</details> 114 115## What is nanomatch? 116 117Nanomatch is a fast and accurate glob matcher with full support for standard Bash glob features, including the following "metacharacters": `*`, `**`, `?` and `[...]`. 118 119**Learn more** 120 121* [Getting started](#getting-started): learn how to install and begin using nanomatch 122* [Features](#features): jump to info about supported patterns, and a glob matching reference 123* [API documentation](#api): jump to available options and methods 124* [Unit tests](test): 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! 125 126<details> 127<summary><strong>How is this different?</strong></summary> 128 129**Speed and accuracy** 130 131Nanomatch uses [snapdragon](https://github.com/jonschlinkert/snapdragon) for parsing and compiling globs, which results in: 132 133* Granular control over the entire conversion process in a way that is easy to understand, reason about, and customize. 134* Faster matching, from a combination of optimized glob patterns and (optional) caching. 135* 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](../../issues), [please let us know](../../issues/new). 136 137**Basic globbing only** 138 139Nanomatch supports [basic globbing only](#features), which is limited to `*`, `**`, `?` and regex-like brackets. 140 141If you need support for the other [bash "expansion" types](#bash-expansion-libs) (in addition to the wildcard matching provided by nanomatch), consider using [micromatch](https://github.com/micromatch/micromatch) instead. _(micromatch >=3.0.0 uses the nanomatch parser and compiler for basic glob matching)_ 142 143</details> 144 145## Getting started 146 147### Installing nanomatch 148 149**Install with [yarn](https://yarnpkg.com/)** 150 151```sh 152$ yarn add nanomatch 153``` 154 155**Install with [npm](https://npmjs.com)** 156 157```sh 158$ npm install nanomatch 159``` 160 161### Usage 162 163Add nanomatch to your project using node's `require()` system: 164 165```js 166var nanomatch = require('nanomatch'); 167 168// the main export is a function that takes an array of strings to match 169// and a string or array of patterns to use for matching 170nanomatch(list, patterns[, options]); 171``` 172 173**Params** 174 175* `list` **{String|Array}**: List of strings to perform matches against. This is often a list of file paths. 176* `patterns` **{String|Array}**: One or more [glob paterns](#features) to use for matching. 177* `options` **{Object}**: Any [supported options](#options) may be passed 178 179**Examples** 180 181```js 182var nm = require('nanomatch'); 183console.log(nm(['a', 'b/b', 'c/c/c'], '*')); 184//=> ['a'] 185 186console.log(nm(['a', 'b/b', 'c/c/c'], '*/*')); 187//=> ['b/b'] 188 189console.log(nm(['a', 'b/b', 'c/c/c'], '**')); 190//=> ['a', 'b/b', 'c/c/c'] 191``` 192 193See the [API documentation](#api) for available methods and [options](https://github.com/einaros/options.js). 194 195## Documentation 196 197### Escaping 198 199_Backslashes and quotes_ can be used to escape characters, forcing nanomatch to regard those characters as a literal characters. 200 201**Backslashes** 202 203Use backslashes to escape single characters. For example, the following pattern would match `foo/*/bar` exactly: 204 205```js 206'foo/\*/bar' 207``` 208 209The following pattern would match `foo/` followed by a literal `*`, followed by zero or more of any characters besides `/`, followed by `/bar`. 210 211```js 212'foo/\**/bar' 213``` 214 215**Quoted strings** 216 217Use single or double quotes to escape sequences of characters. For example, the following patterns would match `foo/**/bar` exactly: 218 219```js 220'foo/"**"/bar' 221'foo/\'**\'/bar' 222"foo/'**'/bar" 223``` 224 225**Matching literal quotes** 226 227If 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`: 228 229```js 230'foo/\\"*\\"/bar' 231``` 232 233And the following will match `foo/'*'/bar`, `foo/'a'/bar`, `foo/'b'/bar`, or `foo/'c'/bar`: 234 235```js 236'foo/\\\'*\\\'/bar' 237``` 238 239## API 240 241### [nanomatch](index.js#L40) 242 243The main function takes a list of strings and one or more glob patterns to use for matching. 244 245**Params** 246 247* `list` **{Array}**: A list of strings to match 248* `patterns` **{String|Array}**: One or more glob patterns to use for matching. 249* `options` **{Object}**: See available [options](#options) for changing how matches are performed 250* `returns` **{Array}**: Returns an array of matches 251 252**Example** 253 254```js 255var nm = require('nanomatch'); 256nm(list, patterns[, options]); 257 258console.log(nm(['a.js', 'a.txt'], ['*.js'])); 259//=> [ 'a.js' ] 260``` 261 262### [.match](index.js#L106) 263 264Similar to the main function, but `pattern` must be a string. 265 266**Params** 267 268* `list` **{Array}**: Array of strings to match 269* `pattern` **{String}**: Glob pattern to use for matching. 270* `options` **{Object}**: See available [options](#options) for changing how matches are performed 271* `returns` **{Array}**: Returns an array of matches 272 273**Example** 274 275```js 276var nm = require('nanomatch'); 277nm.match(list, pattern[, options]); 278 279console.log(nm.match(['a.a', 'a.aa', 'a.b', 'a.c'], '*.a')); 280//=> ['a.a', 'a.aa'] 281``` 282 283### [.isMatch](index.js#L167) 284 285Returns true if the specified `string` matches the given glob `pattern`. 286 287**Params** 288 289* `string` **{String}**: String to match 290* `pattern` **{String}**: Glob pattern to use for matching. 291* `options` **{Object}**: See available [options](#options) for changing how matches are performed 292* `returns` **{Boolean}**: Returns true if the string matches the glob pattern. 293 294**Example** 295 296```js 297var nm = require('nanomatch'); 298nm.isMatch(string, pattern[, options]); 299 300console.log(nm.isMatch('a.a', '*.a')); 301//=> true 302console.log(nm.isMatch('a.b', '*.a')); 303//=> false 304``` 305 306### [.some](index.js#L205) 307 308Returns true if some of the elements in the given `list` match any of the given glob `patterns`. 309 310**Params** 311 312* `list` **{String|Array}**: The string or array of strings to test. Returns as soon as the first match is found. 313* `patterns` **{String|Array}**: One or more glob patterns to use for matching. 314* `options` **{Object}**: See available [options](#options) for changing how matches are performed 315* `returns` **{Boolean}**: Returns true if any patterns match `str` 316 317**Example** 318 319```js 320var nm = require('nanomatch'); 321nm.some(list, patterns[, options]); 322 323console.log(nm.some(['foo.js', 'bar.js'], ['*.js', '!foo.js'])); 324// true 325console.log(nm.some(['foo.js'], ['*.js', '!foo.js'])); 326// false 327``` 328 329### [.every](index.js#L243) 330 331Returns true if every element in the given `list` matches at least one of the given glob `patterns`. 332 333**Params** 334 335* `list` **{String|Array}**: The string or array of strings to test. 336* `patterns` **{String|Array}**: One or more glob patterns to use for matching. 337* `options` **{Object}**: See available [options](#options) for changing how matches are performed 338* `returns` **{Boolean}**: Returns true if any patterns match `str` 339 340**Example** 341 342```js 343var nm = require('nanomatch'); 344nm.every(list, patterns[, options]); 345 346console.log(nm.every('foo.js', ['foo.js'])); 347// true 348console.log(nm.every(['foo.js', 'bar.js'], ['*.js'])); 349// true 350console.log(nm.every(['foo.js', 'bar.js'], ['*.js', '!foo.js'])); 351// false 352console.log(nm.every(['foo.js'], ['*.js', '!foo.js'])); 353// false 354``` 355 356### [.any](index.js#L277) 357 358Returns true if **any** of the given glob `patterns` match the specified `string`. 359 360**Params** 361 362* `str` **{String|Array}**: The string to test. 363* `patterns` **{String|Array}**: One or more glob patterns to use for matching. 364* `options` **{Object}**: See available [options](#options) for changing how matches are performed 365* `returns` **{Boolean}**: Returns true if any patterns match `str` 366 367**Example** 368 369```js 370var nm = require('nanomatch'); 371nm.any(string, patterns[, options]); 372 373console.log(nm.any('a.a', ['b.*', '*.a'])); 374//=> true 375console.log(nm.any('a.a', 'b.*')); 376//=> false 377``` 378 379### [.all](index.js#L325) 380 381Returns true if **all** of the given `patterns` match the specified string. 382 383**Params** 384 385* `str` **{String|Array}**: The string to test. 386* `patterns` **{String|Array}**: One or more glob patterns to use for matching. 387* `options` **{Object}**: See available [options](#options) for changing how matches are performed 388* `returns` **{Boolean}**: Returns true if any patterns match `str` 389 390**Example** 391 392```js 393var nm = require('nanomatch'); 394nm.all(string, patterns[, options]); 395 396console.log(nm.all('foo.js', ['foo.js'])); 397// true 398 399console.log(nm.all('foo.js', ['*.js', '!foo.js'])); 400// false 401 402console.log(nm.all('foo.js', ['*.js', 'foo.js'])); 403// true 404 405console.log(nm.all('foo.js', ['*.js', 'f*', '*o*', '*o.js'])); 406// true 407``` 408 409### [.not](index.js#L359) 410 411Returns a list of strings that _**do not match any**_ of the given `patterns`. 412 413**Params** 414 415* `list` **{Array}**: Array of strings to match. 416* `patterns` **{String|Array}**: One or more glob pattern to use for matching. 417* `options` **{Object}**: See available [options](#options) for changing how matches are performed 418* `returns` **{Array}**: Returns an array of strings that **do not match** the given patterns. 419 420**Example** 421 422```js 423var nm = require('nanomatch'); 424nm.not(list, patterns[, options]); 425 426console.log(nm.not(['a.a', 'b.b', 'c.c'], '*.a')); 427//=> ['b.b', 'c.c'] 428``` 429 430### [.contains](index.js#L394) 431 432Returns true if the given `string` contains the given pattern. Similar to [.isMatch](#isMatch) but the pattern can match any part of the string. 433 434**Params** 435 436* `str` **{String}**: The string to match. 437* `patterns` **{String|Array}**: Glob pattern to use for matching. 438* `options` **{Object}**: See available [options](#options) for changing how matches are performed 439* `returns` **{Boolean}**: Returns true if the patter matches any part of `str`. 440 441**Example** 442 443```js 444var nm = require('nanomatch'); 445nm.contains(string, pattern[, options]); 446 447console.log(nm.contains('aa/bb/cc', '*b')); 448//=> true 449console.log(nm.contains('aa/bb/cc', '*d')); 450//=> false 451``` 452 453### [.matchKeys](index.js#L450) 454 455Filter 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](https://github.com/jonschlinkert/glob-object) instead. 456 457**Params** 458 459* `object` **{Object}**: The object with keys to filter. 460* `patterns` **{String|Array}**: One or more glob patterns to use for matching. 461* `options` **{Object}**: See available [options](#options) for changing how matches are performed 462* `returns` **{Object}**: Returns an object with only keys that match the given patterns. 463 464**Example** 465 466```js 467var nm = require('nanomatch'); 468nm.matchKeys(object, patterns[, options]); 469 470var obj = { aa: 'a', ab: 'b', ac: 'c' }; 471console.log(nm.matchKeys(obj, '*b')); 472//=> { ab: 'b' } 473``` 474 475### [.matcher](index.js#L479) 476 477Returns 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. 478 479**Params** 480 481* `pattern` **{String}**: Glob pattern 482* `options` **{Object}**: See available [options](#options) for changing how matches are performed. 483* `returns` **{Function}**: Returns a matcher function. 484 485**Example** 486 487```js 488var nm = require('nanomatch'); 489nm.matcher(pattern[, options]); 490 491var isMatch = nm.matcher('*.!(*a)'); 492console.log(isMatch('a.a')); 493//=> false 494console.log(isMatch('a.b')); 495//=> true 496``` 497 498### [.capture](index.js#L560) 499 500Returns an array of matches captured by `pattern` in `string, or`null` if the pattern did not match. 501 502**Params** 503 504* `pattern` **{String}**: Glob pattern to use for matching. 505* `string` **{String}**: String to match 506* `options` **{Object}**: See available [options](#options) for changing how matches are performed 507* `returns` **{Boolean}**: Returns an array of captures if the string matches the glob pattern, otherwise `null`. 508 509**Example** 510 511```js 512var nm = require('nanomatch'); 513nm.capture(pattern, string[, options]); 514 515console.log(nm.capture('test/*.js', 'test/foo.js')); 516//=> ['foo'] 517console.log(nm.capture('test/*.js', 'foo/bar.css')); 518//=> null 519``` 520 521### [.makeRe](index.js#L595) 522 523Create a regular expression from the given glob `pattern`. 524 525**Params** 526 527* `pattern` **{String}**: A glob pattern to convert to regex. 528* `options` **{Object}**: See available [options](#options) for changing how matches are performed. 529* `returns` **{RegExp}**: Returns a regex created from the given pattern. 530 531**Example** 532 533```js 534var nm = require('nanomatch'); 535nm.makeRe(pattern[, options]); 536 537console.log(nm.makeRe('*.js')); 538//=> /^(?:(\.[\\\/])?(?!\.)(?=.)[^\/]*?\.js)$/ 539``` 540 541### [.create](index.js#L658) 542 543Parses the given glob `pattern` and returns an object with the compiled `output` and optional source `map`. 544 545**Params** 546 547* `pattern` **{String}**: Glob pattern to parse and compile. 548* `options` **{Object}**: Any [options](#options) to change how parsing and compiling is performed. 549* `returns` **{Object}**: Returns an object with the parsed AST, compiled string and optional source map. 550 551**Example** 552 553```js 554var nm = require('nanomatch'); 555nm.create(pattern[, options]); 556 557console.log(nm.create('abc/*.js')); 558// { options: { source: 'string', sourcemap: true }, 559// state: {}, 560// compilers: 561// { ... }, 562// output: '(\\.[\\\\\\/])?abc\\/(?!\\.)(?=.)[^\\/]*?\\.js', 563// ast: 564// { type: 'root', 565// errors: [], 566// nodes: 567// [ ... ], 568// dot: false, 569// input: 'abc/*.js' }, 570// parsingErrors: [], 571// map: 572// { version: 3, 573// sources: [ 'string' ], 574// names: [], 575// mappings: 'AAAA,GAAG,EAAC,kBAAC,EAAC,EAAE', 576// sourcesContent: [ 'abc/*.js' ] }, 577// position: { line: 1, column: 28 }, 578// content: {}, 579// files: {}, 580// idx: 6 } 581``` 582 583### [.parse](index.js#L697) 584 585Parse the given `str` with the given `options`. 586 587**Params** 588 589* `str` **{String}** 590* `options` **{Object}** 591* `returns` **{Object}**: Returns an AST 592 593**Example** 594 595```js 596var nm = require('nanomatch'); 597nm.parse(pattern[, options]); 598 599var ast = nm.parse('a/{b,c}/d'); 600console.log(ast); 601// { type: 'root', 602// errors: [], 603// input: 'a/{b,c}/d', 604// nodes: 605// [ { type: 'bos', val: '' }, 606// { type: 'text', val: 'a/' }, 607// { type: 'brace', 608// nodes: 609// [ { type: 'brace.open', val: '{' }, 610// { type: 'text', val: 'b,c' }, 611// { type: 'brace.close', val: '}' } ] }, 612// { type: 'text', val: '/d' }, 613// { type: 'eos', val: '' } ] } 614``` 615 616### [.compile](index.js#L745) 617 618Compile the given `ast` or string with the given `options`. 619 620**Params** 621 622* `ast` **{Object|String}** 623* `options` **{Object}** 624* `returns` **{Object}**: Returns an object that has an `output` property with the compiled string. 625 626**Example** 627 628```js 629var nm = require('nanomatch'); 630nm.compile(ast[, options]); 631 632var ast = nm.parse('a/{b,c}/d'); 633console.log(nm.compile(ast)); 634// { options: { source: 'string' }, 635// state: {}, 636// compilers: 637// { eos: [Function], 638// noop: [Function], 639// bos: [Function], 640// brace: [Function], 641// 'brace.open': [Function], 642// text: [Function], 643// 'brace.close': [Function] }, 644// output: [ 'a/(b|c)/d' ], 645// ast: 646// { ... }, 647// parsingErrors: [] } 648``` 649 650### [.clearCache](index.js#L768) 651 652Clear the regex cache. 653 654**Example** 655 656```js 657nm.clearCache(); 658``` 659 660## Options 661 662<details> 663<summary><strong>basename</strong></summary> 664 665### options.basename 666 667Allow glob patterns without slashes to match a file path based on its basename. Same behavior as [minimatch](https://github.com/isaacs/minimatch) option `matchBase`. 668 669Type: `boolean` 670 671Default: `false` 672 673**Example** 674 675```js 676nm(['a/b.js', 'a/c.md'], '*.js'); 677//=> [] 678 679nm(['a/b.js', 'a/c.md'], '*.js', {matchBase: true}); 680//=> ['a/b.js'] 681``` 682 683</details> 684 685<details> 686<summary><strong>bash</strong></summary> 687 688### options.bash 689 690Enabled 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. 691 692Type: `boolean` 693 694Default: `true` 695 696**Example** 697 698```js 699var files = ['abc', 'ajz']; 700console.log(nm(files, '[a-c]*')); 701//=> ['abc', 'ajz'] 702 703console.log(nm(files, '[a-c]*', {bash: false})); 704``` 705 706</details> 707 708<details> 709<summary><strong>cache</strong></summary> 710 711### options.cache 712 713Disable regex and function memoization. 714 715Type: `boolean` 716 717Default: `undefined` 718 719</details> 720 721<details> 722<summary><strong>dot</strong></summary> 723 724### options.dot 725 726Match dotfiles. Same behavior as [minimatch](https://github.com/isaacs/minimatch) option `dot`. 727 728Type: `boolean` 729 730Default: `false` 731 732</details> 733 734<details> 735<summary><strong>failglob</strong></summary> 736 737### options.failglob 738 739Similar to the `--failglob` behavior in Bash, throws an error when no matches are found. 740 741Type: `boolean` 742 743Default: `undefined` 744 745</details> 746 747<details> 748<summary><strong>ignore</strong></summary> 749 750### options.ignore 751 752String or array of glob patterns to match files to ignore. 753 754Type: `String|Array` 755 756Default: `undefined` 757 758</details> 759 760<details> 761<summary><strong>matchBase</strong></summary> 762 763### options.matchBase 764 765Alias for [options.basename](#options-basename). 766 767</details> 768 769<details> 770<summary><strong>nocase</strong></summary> 771 772### options.nocase 773 774Use a case-insensitive regex for matching files. Same behavior as [minimatch](https://github.com/isaacs/minimatch). 775 776Type: `boolean` 777 778Default: `undefined` 779 780</details> 781 782<details> 783<summary><strong>nodupes</strong></summary> 784 785### options.nodupes 786 787Remove duplicate elements from the result array. 788 789Type: `boolean` 790 791Default: `true` (enabled by default) 792 793**Example** 794 795Example of using the `unescape` and `nodupes` options together: 796 797```js 798nm.match(['a/b/c', 'a/b/c'], '**'); 799//=> ['abc'] 800 801nm.match(['a/b/c', 'a/b/c'], '**', {nodupes: false}); 802//=> ['a/b/c', 'a/b/c'] 803``` 804 805</details> 806 807<details> 808<summary><strong>nonegate</strong></summary> 809 810### options.noglobstar 811 812Disable matching with globstars (`**`). 813 814Type: `boolean` 815 816Default: `undefined` 817 818```js 819nm(['a/b', 'a/b/c', 'a/b/c/d'], 'a/**'); 820//=> ['a/b', 'a/b/c', 'a/b/c/d'] 821 822nm(['a/b', 'a/b/c', 'a/b/c/d'], 'a/**', {noglobstar: true}); 823//=> ['a/b'] 824``` 825 826</details> 827 828<details> 829<summary><strong>nonegate</strong></summary> 830 831### options.nonegate 832 833Disallow negation (`!`) patterns, and treat leading `!` as a literal character to match. 834 835Type: `boolean` 836 837Default: `undefined` 838 839</details> 840 841<details> 842<summary><strong>nonull</strong></summary> 843 844### options.nonull 845 846Alias for [options.nullglob](#options-nullglob). 847 848</details> 849 850<details> 851<summary><strong>nullglob</strong></summary> 852 853### options.nullglob 854 855If `true`, when no matches are found the actual (arrayified) glob pattern is returned instead of an empty array. Same behavior as [minimatch](https://github.com/isaacs/minimatch) option `nonull`. 856 857Type: `boolean` 858 859Default: `undefined` 860 861</details> 862 863<details> 864<summary><strong><a name="slash">slash</a></strong></summary> 865 866### options.slash 867 868Customize the slash character(s) to use for matching. 869 870Type: `string|function` 871 872Default: `[/\\]` (forward slash and backslash) 873 874</details> 875 876<details> 877<summary><strong><a name="star">star</a></strong></summary> 878 879### options.star 880 881Customize 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. 882 883Type: `string|function` 884 885Default: `[^/\\]*?` 886 887</details> 888 889<details> 890<summary><strong><a name="snapdragon">snapdragon</a></strong></summary> 891 892### options.snapdragon 893 894Pass your own instance of [snapdragon](https://github.com/jonschlinkert/snapdragon) to customize parsers or compilers. 895 896Type: `object` 897 898Default: `undefined` 899 900</details> 901 902<details> 903<summary><strong>snapdragon</strong></summary> 904 905### options.sourcemap 906 907Generate a source map by enabling the `sourcemap` option with the `.parse`, `.compile`, or `.create` methods. 908 909**Examples** 910 911```js 912var nm = require('nanomatch'); 913 914var res = nm.create('abc/*.js', {sourcemap: true}); 915console.log(res.map); 916// { version: 3, 917// sources: [ 'string' ], 918// names: [], 919// mappings: 'AAAA,GAAG,EAAC,iBAAC,EAAC,EAAE', 920// sourcesContent: [ 'abc/*.js' ] } 921 922var ast = nm.parse('abc/**/*.js'); 923var res = nm.compile(ast, {sourcemap: true}); 924console.log(res.map); 925// { version: 3, 926// sources: [ 'string' ], 927// names: [], 928// mappings: 'AAAA,GAAG,EAAC,2BAAE,EAAC,iBAAC,EAAC,EAAE', 929// sourcesContent: [ 'abc/**/*.js' ] } 930``` 931 932</details> 933 934<details> 935<summary><strong>unescape</strong></summary> 936 937### options.unescape 938 939Remove backslashes from returned matches. 940 941Type: `boolean` 942 943Default: `undefined` 944 945**Example** 946 947In this example we want to match a literal `*`: 948 949```js 950nm.match(['abc', 'a\\*c'], 'a\\*c'); 951//=> ['a\\*c'] 952 953nm.match(['abc', 'a\\*c'], 'a\\*c', {unescape: true}); 954//=> ['a*c'] 955``` 956 957</details> 958 959<details> 960<summary><strong>unixify</strong></summary> 961 962### options.unixify 963 964Convert path separators on returned files to posix/unix-style forward slashes. 965 966Type: `boolean` 967 968Default: `true` 969 970**Example** 971 972```js 973nm.match(['a\\b\\c'], 'a/**'); 974//=> ['a/b/c'] 975 976nm.match(['a\\b\\c'], {unixify: false}); 977//=> ['a\\b\\c'] 978``` 979 980</details> 981 982## Features 983 984Nanomatch has full support for standard Bash glob features, including the following "metacharacters": `*`, `**`, `?` and `[...]`. 985 986Here are some examples of how they work: 987 988| **Pattern** | **Description** | 989| --- | --- | 990| `*` | Matches any string except for `/`, leading `.`, or `/.` inside a path | 991| `**` | 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 | when it's not the only thing in a path segment, per Bash specifications) | 992| `foo*` | Matches any string beginning with `foo` | 993| `*bar*` | Matches any string containing `bar` (beginning, middle or end) | 994| `*.min.js` | Matches any string ending with `.min.js` | 995| `[abc]*.js` | Matches any string beginning with `a`, `b`, or `c` and ending with `.js` | 996| `abc?` | Matches `abcd` or `abcz` but not `abcde` | 997 998The exceptions noted for `*` apply to all patterns that contain a `*`. 999 1000**Not supported** 1001 1002The following extended-globbing features are not supported: 1003 1004* [brace expansion](https://github.com/jonschlinkert/braces) (e.g. `{a,b,c}`) 1005* [extglobs](https://github.com/jonschlinkert/extglob) (e.g. `@(a|!(c|d))`) 1006* [POSIX brackets](https://github.com/jonschlinkert/expand-brackets) (e.g. `[[:alpha:][:digit:]]`) 1007 1008If you need any of these features consider using [micromatch](https://github.com/micromatch/micromatch) instead. 1009 1010## Bash expansion libs 1011 1012Nanomatch is part of a suite of libraries aimed at bringing the power and expressiveness of [Bash's](https://www.gnu.org/software/bash/) matching and expansion capabilities to JavaScript, _and - as you can see by the [benchmarks](#benchmarks) - without sacrificing speed_. 1013 1014| **Related library** | **Matching Type** | **Example** | **Description** | 1015| --- | --- | --- | --- | 1016| `nanomatch` (you are here) | Wildcards | `*` | [Filename expansion](https://www.gnu.org/software/bash/manual/html_node/Filename-Expansion.html#Filename-Expansion), also referred to as globbing and pathname expansion, allows the use of [wildcards](#features) for matching. | 1017| [expand-tilde](https://github.com/jonschlinkert/expand-tilde) | Tildes | `~` | [Tilde expansion](https://www.gnu.org/software/bash/manual/html_node/Tilde-Expansion.html#Tilde-Expansion) converts the leading tilde in a file path to the user home directory. | 1018| [braces](https://github.com/jonschlinkert/braces) | Braces | `{a,b,c}` | [Brace expansion](https://www.gnu.org/software/bash/manual/html_node/Brace-Expansion.html) | 1019| [expand-brackets](https://github.com/jonschlinkert/expand-brackets) | Brackets | `[[:alpha:]]` | [POSIX character classes](https://www.gnu.org/software/grep/manual/html_node/Character-Classes-and-Bracket-Expressions.html) (also referred to as POSIX brackets, or POSIX character classes) | 1020| [extglob](https://github.com/jonschlinkert/extglob) | Parens | `!(a\ | b)` | [Extglobs](https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html#Pattern-Matching) | 1021| [micromatch](https://github.com/micromatch/micromatch) | All | all | Micromatch is built on top of the other libraries. | 1022 1023There are many resources available on the web if you want to dive deeper into how these features work in Bash. 1024 1025## Benchmarks 1026 1027### Running benchmarks 1028 1029Install dev dependencies: 1030 1031```bash 1032npm i -d && node benchmark 1033``` 1034 1035### Nanomatch vs. Minimatch vs. Multimatch 1036 1037```bash 1038# globstar-basic (182 bytes) 1039 minimatch x 69,512 ops/sec ±1.92% (88 runs sampled) 1040 multimatch x 63,376 ops/sec ±1.41% (89 runs sampled) 1041 nanomatch x 432,451 ops/sec ±0.92% (88 runs sampled) 1042 1043 fastest is nanomatch (by 651% avg) 1044 1045# large-list-globstar (485686 bytes) 1046 minimatch x 34.02 ops/sec ±1.42% (59 runs sampled) 1047 multimatch x 33.58 ops/sec ±1.97% (58 runs sampled) 1048 nanomatch x 483 ops/sec ±1.06% (86 runs sampled) 1049 1050 fastest is nanomatch (by 1429% avg) 1051 1052# long-list-globstar (194085 bytes) 1053 minimatch x 383 ops/sec ±0.74% (90 runs sampled) 1054 multimatch x 378 ops/sec ±0.59% (89 runs sampled) 1055 nanomatch x 990 ops/sec ±1.14% (85 runs sampled) 1056 1057 fastest is nanomatch (by 260% avg) 1058 1059# negation-basic (132 bytes) 1060 minimatch x 242,145 ops/sec ±1.17% (89 runs sampled) 1061 multimatch x 76,403 ops/sec ±0.78% (92 runs sampled) 1062 nanomatch x 537,253 ops/sec ±1.44% (86 runs sampled) 1063 1064 fastest is nanomatch (by 337% avg) 1065 1066# not-glob-basic (93 bytes) 1067 minimatch x 252,402 ops/sec ±1.33% (89 runs sampled) 1068 multimatch x 209,954 ops/sec ±1.30% (90 runs sampled) 1069 nanomatch x 1,716,468 ops/sec ±1.13% (86 runs sampled) 1070 1071 fastest is nanomatch (by 742% avg) 1072 1073# star-basic (93 bytes) 1074 minimatch x 182,780 ops/sec ±1.41% (91 runs sampled) 1075 multimatch x 153,210 ops/sec ±0.72% (89 runs sampled) 1076 nanomatch x 599,621 ops/sec ±1.22% (90 runs sampled) 1077 1078 fastest is nanomatch (by 357% avg) 1079 1080``` 1081 1082## About 1083 1084<details> 1085<summary><strong>Contributing</strong></summary> 1086 1087Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). 1088 1089Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards. 1090 1091</details> 1092 1093<details> 1094<summary><strong>Running Tests</strong></summary> 1095 1096Running 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: 1097 1098```sh 1099$ npm install && npm test 1100``` 1101 1102</details> 1103 1104<details> 1105<summary><strong>Building docs</strong></summary> 1106 1107_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_ 1108 1109To generate the readme, run the following command: 1110 1111```sh 1112$ npm install -g verbose/verb#dev verb-generate-readme && verb 1113``` 1114 1115</details> 1116 1117### Related projects 1118 1119You might also be interested in these projects: 1120 1121* [extglob](https://www.npmjs.com/package/extglob): Extended glob support for JavaScript. Adds (almost) the expressive power of regular expressions to glob… [more](https://github.com/micromatch/extglob) | [homepage](https://github.com/micromatch/extglob "Extended glob support for JavaScript. Adds (almost) the expressive power of regular expressions to glob patterns.") 1122* [is-extglob](https://www.npmjs.com/package/is-extglob): Returns true if a string has an extglob. | [homepage](https://github.com/jonschlinkert/is-extglob "Returns true if a string has an extglob.") 1123* [is-glob](https://www.npmjs.com/package/is-glob): Returns `true` if the given string looks like a glob pattern or an extglob pattern… [more](https://github.com/jonschlinkert/is-glob) | [homepage](https://github.com/jonschlinkert/is-glob "Returns `true` if the given string looks like a glob pattern or an extglob pattern. This makes it easy to create code that only uses external modules like node-glob when necessary, resulting in much faster code execution and initialization time, and a bet") 1124* [micromatch](https://www.npmjs.com/package/micromatch): Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. | [homepage](https://github.com/micromatch/micromatch "Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch.") 1125 1126### Contributors 1127 1128| **Commits** | **Contributor** | 1129| --- | --- | 1130| 164 | [jonschlinkert](https://github.com/jonschlinkert) | 1131| 1 | [devongovett](https://github.com/devongovett) | 1132 1133### Author 1134 1135**Jon Schlinkert** 1136 1137* [linkedin/in/jonschlinkert](https://linkedin.com/in/jonschlinkert) 1138* [github/jonschlinkert](https://github.com/jonschlinkert) 1139* [twitter/jonschlinkert](https://twitter.com/jonschlinkert) 1140 1141### License 1142 1143Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert). 1144Released under the [MIT License](LICENSE). 1145 1146*** 1147 1148_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on February 18, 2018._