Multi-pattern matchers
A list of patterns compiles into one matcher that answers with boolean OR: a path matches when any member matches. This page covers what the union means, how negated members behave in each language, and how directory verdicts combine.
One matcher, OR semantics
import { globstar, compileMatcher } from "@globstar/core";
const isDoc = globstar(["**/*.md", "docs/**"]);
isDoc("README.md"); // true
isDoc("docs/assets/logo.svg"); // true
isDoc("src/index.ts"); // false
const m = compileMatcher(["src/**/*.ts", "docs/**/*.md"]);use globstar::Glob;
let glob = Glob::union(["**/*.md", "docs/**"])?;
assert!(glob.is_match(b"README.md"));
assert!(glob.is_match(b"docs/assets/logo.svg"));
assert!(!glob.is_match(b"src/index.ts"));The union is OR, never AND. There is no API that tells you which member matched; the matcher answers the boolean questions only (match, matchDir, staticPrefixes). A pattern given twice counts once. In Rust the union is an ordinary Glob, not a separate set type.
Spec: GLOB_SPEC §16.1
Negated members
A leading ! makes a pattern match everything its body does not. In a union the member contributes its complement to the OR; it does not subtract from the other members.
const m = globstar(["src/**", "!src/**/*.test.ts"]);
m("src/a.ts"); // true: matches src/**
m("src/a.test.ts"); // true: matches src/**
m("lib/x.js"); // true: matches the complement of src/**/*.test.tsThe two languages treat this differently:
- JavaScript accepts negated members and applies the rule above.
["src/**", "!src/**"]matches every path. - Rust rejects a negated member in
Glob::unionwithGlobError::NegatedInUnion, because the result is almost never intended.
Include/exclude filtering belongs to the walker layer. @globstar/walk and globstar-walk split !-patterns out of the list into an ignore set, and that is the way to express "everything in src, except tests". See Pattern syntax for how the leading ! is counted.
WARNING
["src/**", "!**/*.test.ts"] as a matcher matches almost everything. Pass the list to a walker, or compile the include and exclude sets as two matchers and combine them yourself.
Directory verdicts on a union
matchDir is computed on the union, not per member and then merged by hand. The rule is conservative in the direction a walker needs:
- The union may match below a directory if any member may.
- The union matches a directory if any member matches it.
- The union matches all below when the members together cover every path below, even when no single member does.
| Patterns | Directory | Verdict | Why |
|---|---|---|---|
src/**, tests/** | lib | Pruned | No member can match under lib. |
src/**, tests/** | src | DescendAll | src/** alone covers everything below (dot). |
a/* | a | Descend | Only the children of a match. |
a/*/** | a | Descend | Only paths two or more levels down match. |
a/*, a/*/** | a | DescendAll | Together they cover every path below a. |
Pruning is safe only when every member says Pruned. See Directory matching for what each verdict means to an include list and to an exclude list.
Spec: GLOB_SPEC §16.2
Static prefixes of a union
staticPrefixes() returns each member's own literal heads (each expansion's literal head up to its last whole segment), shortest first, with prefixes covered by a shorter one removed. What the union shares does not shorten them: ["node_modules/react/package.json", "node_modules/vue/package.json"] gives both full paths. A member that can match at the root (such as **/*.ts) makes the whole list the single empty prefix.
compileMatcher(["src/**/*.ts", "docs/**/*.md"]).staticPrefixes(); // src, docs
compileMatcher(["src/**/*.ts", "**/*.md"]).staticPrefixes(); // "" (the root)Errors
- An empty list fails with
EmptyPatternSetin both languages. - Any member that fails to compile fails the whole union: Rust wraps the member's error in
InMember { index, error }, JS addsindexto it. A list of members that each compile compiles: the members share no budget. - Rust: a
!-member fails withNegatedInUnion, which carries the member's index and text.
Spec: GLOB_SPEC §6, §16