Skip to content

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 ​

js
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"]);
rust
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.

js
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.ts

The 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::union with GlobError::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.
PatternsDirectoryVerdictWhy
src/**, tests/**libPrunedNo member can match under lib.
src/**, tests/**srcDescendAllsrc/** alone covers everything below (dot).
a/*aDescendOnly the children of a match.
a/*/**aDescendOnly paths two or more levels down match.
a/*, a/*/**aDescendAllTogether 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.

js
compileMatcher(["src/**/*.ts", "docs/**/*.md"]).staticPrefixes(); // src, docs
compileMatcher(["src/**/*.ts", "**/*.md"]).staticPrefixes(); // "" (the root)

Errors ​

  • An empty list fails with EmptyPatternSet in both languages.
  • Any member that fails to compile fails the whole union: Rust wraps the member's error in InMember { index, error }, JS adds index to it. A list of members that each compile compiles: the members share no budget.
  • Rust: a !-member fails with NegatedInUnion, which carries the member's index and text.

Spec: GLOB_SPEC §6, §16

Released under the MIT License.