Skip to content

Pattern syntax ​

This page lists every construct of a pattern, what each one matches, and which characters must be escaped. The ** wildcard, character classes, and braces each have their own page with more detail: see The ** wildcard, Character classes, and Brace expansion.

All examples use the default options (dot: true, caseInsensitive: false). See How a path is matched for how dot and case-insensitivity change the results.

Quick reference ​

ConstructMatchesExample
abcexactly these charactersREADME.md
?one character, never /file?.txt
*zero or more characters inside one path segment*.ts
**zero or more whole segments (it crosses /)src/**/*.ts
[abc], [a-z]one character from a set*.[jt]s
[!abc], [^abc]one character not in the set[!_]*.ts
{a,b}any one of the branches*.{js,ts}
\Xthe character X itself\*.md
! at the very starteverything the rest of the pattern does not match!*.test.ts

Three rules ​

  • A pattern matches the whole path, never a part of it.
  • Matching is byte by byte in UTF-8: ? and a class take one byte, and a character outside ASCII is a literal (docs/日本語.md matches only that path).
  • In a pattern, / is the only separator on every platform, and \ is always an escape.

How a path is matched explains each rule with examples, and what \ means on the path side.

Meta-characters ​

These characters can have a special meaning: * ? [ ] { } , \, plus ! at the very start of a pattern. Some are special everywhere; others only in one place.

CharacterSpecial whenOtherwise
*, ?always (wildcards)—
[always: opens a class, which must be closed—
]it closes an open classliteral
{always: opens a brace, which must be closed—
}it closes an open braceliteral
,inside a brace (splits branches)literal
\always (escapes the next character)—
!it is at the very start of the patternliteral
(, ), @, +, |neverliteral

A closer with nothing open is literal: a]b matches the path a]b, and a}b matches a}b. An opener with no closer is an error: [a and {a both fail to compile. See Compile-time errors.

Spec: GLOB_SPEC §4.1

Basic constructs ​

Literals ​

Any character that is not a meta-character matches itself, exactly once. README.md matches only README.md.

? — one character ​

? matches exactly one character that is not a separator. It never matches an empty string.

PatternPathMatch?
file?.txtfile1.txtyes
file?.txtfile10.txtno
file?.txtfile.txtno
a?ba/bno

* — anything inside one segment ​

* matches zero or more characters, but it stops at /. It can match nothing at all.

PatternPathMatch?
foo*barfoobaryes
foo*barfoo-baryes
foo*barfoo/barno
src/*.tssrc/main.tsyes
src/*.tssrc/util/x.tsno

With dot: false, ? and * do not match a . at the start of a segment, so *.ts no longer matches .ts. See How a path is matched.

** — any depth ​

** is the only construct that crosses /. It must stand alone as a whole segment, like src/**/*.ts. Written next to other characters, as in src/**.ts, it acts like a single *. The rules are on The ** wildcard page.

PatternPathMatch?
src/**/*.tssrc/a.tsyes
src/**/*.tssrc/a/b.tsyes
src/**.tssrc/a/b.tsno

The empty pattern ​

The empty string "" is not a valid pattern. Compiling it throws a GlobError with kind Empty.

Spec: GLOB_SPEC §7

What is not supported ​

The following shell and glob-library syntax is not part of the dialect. Each form still compiles, with a plain meaning.

  • Extglobs such as @(a|b), +(x), *(x), ?(x), !(x). The parentheses, @, and + are plain characters. A * or ? inside still works as a wildcard. Use a brace like {foo,bar}.js instead.
  • POSIX classes such as [[:alpha:]]. This is not a "letter" class, so it does not match a. Write [a-zA-Z] instead.
  • Brace ranges such as {1..10} or {a..z}. A brace needs a comma, so {1..3}.txt is literal. Write {1,2,3} or [1-3] instead.
  • Regex features: groups, backreferences such as \1, lookahead, lookbehind.
  • Shell expansion: ~ and $VAR are plain characters. Expand them yourself before you compile.
PatternPathMatch?
+(foo).jsfoo.jsno
+(foo).js+(foo).jsyes
*(x).jsabc(x).jsyes
[[:alpha:]]ano
{1..3}.txt1.txtno
{1..3}.txt{1..3}.txtyes
file(1).txtfile(1).txtyes
~/x~/xyes

Spec: GLOB_SPEC §1.2

Escaping with \ ​

A backslash makes the next character literal. This works on any character: \* is a literal *, and \a is just a. Two forms are errors:

  • \/ throws EscapedSeparator. A file name can never contain /, so this could never match.
  • A \ at the very end, as in foo\, throws TrailingBackslash.
PatternPathMatch?
\*.md*.mdyes
\*.mdREADME.mdno
what\?.txtwhat?.txtyes
what\?.txtwhatx.txtno
\[draft\].md[draft].mdyes
[draft].mdd.mdyes
\\\yes

In the last two rows, [draft] without escapes is a class that matches one letter.

What needs escaping, and where ​

To match a literalWriteWhy
* or ?\*, \?they are always wildcards
[\[a bare [ opens a class
{\{a bare { opens a brace; \{a,b} matches the path {a,b}
] or }], } (escape optional)literal when nothing is open
, inside a brace\,a bare , splits branches; {a\,b,c} matches a,b
\\\a bare \ escapes the next character
! as the first character\!a leading ! negates the pattern

Backslashes in source code

In a JavaScript string, \ is also an escape, so the pattern \*.md is written '\\*.md' (or String.raw with `\*.md`). In Rust, use a raw string: r"\*.md".

Spec: GLOB_SPEC §4.2

Negation with a leading ! ​

A ! at the very start of a pattern flips the result: the pattern matches every path the rest of it does not match. globstar counts the whole run of leading !. An odd count negates; an even count cancels out.

PatternPathMatch?
!*.test.tsapp.test.tsno
!*.test.tsapp.tsyes
!!*.tsa.tsyes
!!!*.tsa.tsno
!node_modules/**src/index.jsyes

Negation always applies to the whole pattern. There is no way to negate just one segment, and a ! anywhere else is a plain character:

PatternPathMatch?
src/!important.mdsrc/!important.mdyes
!(foo)fooyes
!(foo)(foo)no
\!foo!fooyes
[\!]foo!fooyes

!(foo) is not an extglob: it is "not the literal path (foo)". To match a name that starts with !, escape it (\!foo) or put it in a class ([\!]foo). Do not write [!]foo: there the ] is a class member, the class never closes, and the pattern fails to compile.

The leading ! is read before braces are expanded, so a ! inside a brace is literal: {!a,b} matches !a and b, but not a.

! in a list of patterns

A list is an OR, so a ! member adds paths instead of removing them. See Negated members.

Spec: GLOB_SPEC §11

Released under the MIT License.