Picomatch

Blazing fast and accurate glob matcher written in JavaScript.

No dependencies and full support for standard and extended Bash glob features, including braces, extglobs, POSIX brackets, and regular expressions.

Why picomatch?

• Lightweight - No dependencies
• Minimal - Tiny API surface. Main export is a function that takes a glob pattern and returns a matcher function.
• Fast - Loads in about 2ms (that's several times faster than a single frame of a HD movie at 60fps)
• Performant - Use the returned matcher function to speed up repeat matching (like when watching files)
• Accurate matching - Using wildcards (* and ?), globstars (**) for nested directories, advanced globbing with extglobs, braces, and POSIX brackets, and support for escaping special characters with \ or quotes.
• Well tested - Thousands of unit tests

See the library comparison to other libraries.

Table of Contents

Click to expand

• Install
• Usage
• API
• picomatch
• .test
• .matchBase
• .isMatch
• .parse
• .scan
• .compileRe
• .makeRe
• .toRegex
• Options
• Picomatch options
• Scan Options
• Options Examples
• Globbing features
• Basic globbing
• Advanced globbing
• Braces
• Matching special characters as literals
• Library Comparisons
• Benchmarks
• Philosophies
• About
• Author
• License

(TOC generated by verb using markdown-toc)

Install

Install with npm:

npm install --save picomatch

Usage

The main export is a function that takes a glob pattern and an options object and returns a function for matching strings.

const pm = require('picomatch');
const isMatch = pm('*.js');

console.log(isMatch('abcd')); //=> false
console.log(isMatch('a.js')); //=> true
console.log(isMatch('a.md')); //=> false
console.log(isMatch('a/b.js')); //=> false

API

picomatch

Creates a matcher function from one or more glob patterns. The returned function takes a string to match as its first argument, and returns true if the string is a match. The returned matcher function also takes a boolean as the second argument that, when true, returns an object with additional information.

Params

• globs {String|Array}: One or more glob patterns.
• options {Object=}
• returns {Function=}: Returns a matcher function.

Example

const picomatch = require('picomatch');
// picomatch(glob[, options]);

const isMatch = picomatch('*.!(*a)');
console.log(isMatch('a.a')); //=> false
console.log(isMatch('a.b')); //=> true

// For environments without `node.js`, `picomatch/posix` provides you a dependency-free matcher, without automatic OS detection.
const picomatch = require('picomatch/posix');
// the same API, defaulting to posix paths
const isMatch = picomatch('a/*');
console.log(isMatch('a\\b')); //=> false
console.log(isMatch('a/b')); //=> true

// you can still configure the matcher function to accept windows paths
const isMatch = picomatch('a/*', { options: windows });
console.log(isMatch('a\\b')); //=> true
console.log(isMatch('a/b')); //=> true

.test

Test input with the given regex. This is used by the main picomatch() function to test the input string.

Params

• input {String}: String to test.
• regex {RegExp}
• returns {Object}: Returns an object with matching info.

Example

const picomatch = require('picomatch');
// picomatch.test(input, regex[, options]);

console.log(picomatch.test('foo/bar', /^(?:([^/]*?)\/([^/]*?))$/));
// { isMatch: true, match: [ 'foo/', 'foo', 'bar' ], output: 'foo/bar' }

.matchBase

Match the basename of a filepath.

Params

• input {String}: String to test.
• glob {RegExp|String}: Glob pattern or regex created by .makeRe.
• returns {Boolean}

Example

const picomatch = require('picomatch');
// picomatch.matchBase(input, glob[, options]);
console.log(picomatch.matchBase('foo/bar.js', '*.js'); // true

.isMatch

Returns true if any of the given glob patterns match the specified string.

Params

• {String|Array}: str The string to test.
• {String|Array}: patterns One or more glob patterns to use for matching.
• {Object}: See available options.
• returns {Boolean}: Returns true if any patterns match str

Example

const picomatch = require('picomatch');
// picomatch.isMatch(string, patterns[, options]);

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

.parse

Parse a glob pattern to create the source string for a regular expression.

Params

• pattern {String}
• options {Object}
• returns {Object}: Returns an object with useful properties and output to be used as a regex source string.

Example

const picomatch = require('picomatch');
const result = picomatch.parse(pattern[, options]);

.scan

Scan a glob pattern to separate the pattern into segments.

Params

• input {String}: Glob pattern to scan.
• options {Object}
• returns {Object}: Returns an object with

Example

const picomatch = require('picomatch');
// picomatch.scan(input[, options]);

const result = picomatch.scan('!./foo/*.js');
console.log(result);
{ prefix: '!./',
  input: '!./foo/*.js',
  start: 3,
  base: 'foo',
  glob: '*.js',
  isBrace: false,
  isBracket: false,
  isGlob: true,
  isExtglob: false,
  isGlobstar: false,
  negated: true }

.compileRe

Compile a regular expression from the state object returned by the parse() method.

Params

• state {Object}
• options {Object}
• returnOutput {Boolean}: Intended for implementors, this argument allows you to return the raw output from the parser.
• returnState {Boolean}: Adds the state to a state property on the returned regex. Useful for implementors and debugging.
• returns {RegExp}

Example

const picomatch = require('picomatch');
const state = picomatch.parse('*.js');
// picomatch.compileRe(state[, options]);

console.log(picomatch.compileRe(state));
//=> /^(?:(?!\.)(?=.)[^/]*?\.js)$/

.makeRe

Create a regular expression from a parsed glob pattern.

Params

• state {String}: The object returned from the .parse method.
• options {Object}
• returnOutput {Boolean}: Implementors may use this argument to return the compiled output, instead of a regular expression. This is not exposed on the options to prevent end-users from mutating the result.
• returnState {Boolean}: Implementors may use this argument to return the state from the parsed glob with the returned regular expression.
• returns {RegExp}: Returns a regex created from the given pattern.

Example

const picomatch = require('picomatch');
// picomatch.makeRe(state[, options]);

const result = picomatch.makeRe('*.js');
console.log(result);
//=> /^(?:(?!\.)(?=.)[^/]*?\.js)$/

.toRegex

Create a regular expression from the given regex source string.

Params

• source {String}: Regular expression source string.
• options {Object}
• returns {RegExp}

Example

const picomatch = require('picomatch');
// picomatch.toRegex(source[, options]);

const { output } = picomatch.parse('*.js');
console.log(picomatch.toRegex(output));
//=> /^(?:(?!\.)(?=.)[^/]*?\.js)$/

Options

Picomatch options

The following options may be used with the main picomatch() function or any of the methods on the picomatch API.

Option	Type	Default value	Description
basename	boolean	false	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.
bash	boolean	false	Follow bash matching rules more strictly - disallows backslashes as escape characters, and treats single stars as globstars (**).
capture	boolean	undefined	Return regex matches in supporting methods.
contains	boolean	undefined	Allows glob to match any part of the given string(s).
debug	boolean	undefined	Debug regular expressions when an error is thrown.
dot	boolean	false	Enable dotfile matching. By default, dotfiles are ignored unless a . is explicitly defined in the pattern, or options.dot is true
expandRange	function	undefined	Custom function for expanding ranges in brace patterns, such as {a..z}. The function receives the range values as two arguments, and it must return a string to be used in the generated regex. It's recommended that returned strings be wrapped in parentheses.
fastpaths	boolean	true	To speed up processing, full parsing is skipped for a handful common glob patterns. Disable this behavior by setting this option to false.
flags	string	undefined	Regex flags to use in the generated regex. If defined, the nocase option will be overridden.
format	function	undefined	Custom function for formatting the returned string. This is useful for removing leading slashes, converting Windows paths to Posix paths, etc.
ignore	array\|string	undefined	One or more glob patterns for excluding strings that should not be matched from the result.
keepQuotes	boolean	false	Retain quotes in the generated regex, since quotes may also be used as an alternative to backslashes.
literalBrackets	boolean	undefined	When true, brackets in the glob pattern will be escaped so that only literal brackets will be matched.
matchBase	boolean	false	Alias for basename
maxLength	number	65536	Limit the max length of the input string. An error is thrown if the input string is longer than this value.
maxExtglobRecursion	number\|boolean	0	Limit nested quantified extglobs and other risky repeated extglob forms. When the limit is exceeded, the extglob is treated as a literal string instead of being compiled to regex. Set to false to disable this safeguard.
nobrace	boolean	false	Disable brace matching, so that {a,b} and {1..3} would be treated as literal characters.
nobracket	boolean	undefined	Disable matching with regex brackets.
nocase	boolean	false	Make matching case-insensitive. Equivalent to the regex i flag. Note that this option is overridden by the flags option.
noext	boolean	false	Alias for noextglob
noextglob	boolean	false	Disable support for matching with extglobs (like +(a\|b))
noglobstar	boolean	false	Disable support for matching nested directories with globstars (**)
nonegate	boolean	false	Disable support for negating with leading !
onIgnore	function	undefined	Function to be called on ignored items.
onMatch	function	undefined	Function to be called on matched items.
onResult	function	undefined	Function to be called on all items, regardless of whether or not they are matched or ignored.
posix	boolean	false	Support POSIX character classes ("posix brackets").
prepend	boolean	undefined	String to prepend to the generated regex used for matching.
regex	boolean	false	Use regular expression rules for + (instead of matching literal +), and for stars that follow closing parentheses or brackets (as in )* and ]*).
strictBrackets	boolean	undefined	Throw an error if brackets, braces, or parens are imb