Skip to content

Directory matching ​

A filesystem walker meets directories before it meets the files inside them. matchDir (Rust: match_dir) lets it ask a pattern about a directory path and skip whole subtrees safely. This page explains the three facts a verdict carries, the six verdicts, and how a pattern that selects files reads them differently from a pattern that excludes files.

Three facts, six verdicts ​

For a directory path d, a pattern answers three questions:

FactQuestionWhich way it errs
matchesDoes d itself match, exactly as a file path would?Exact.
may match belowCould some path d/… match?false is a guarantee; true may be cautious.
matches all belowDoes every path d/… match (… alone at the root ""), for every … of one or more non-empty segments?true is a guarantee; false may be cautious.

"All below" implies "may below", so the three bits form six consistent combinations. Each is a verdict:

Verdictmatchesmay match belowmatches all belowExample
Prunednononosrc/**/*.ts against lib
Matchyesnonosrc against src
Descendnoyesnosrc/**/*.ts against src
DescendAndMatchyesyesnosrc{,/**/*.ts} against src
DescendAllnoyesyesdist/** against dist (with dot)
DescendAllAndMatchyesyesyes** against a

The names read from the pattern's side: the pattern matches the directory, descends below it, or is pruned there. What a walker does with a verdict depends on the role the pattern plays, so walkers read the facts, not the names:

js
import { compileMatcher, DirMatch } from "@globstar/core";

const d = compileMatcher("src/**/*.ts").matchDir("src");
DirMatch.matches(d); // false
DirMatch.mayMatchBelow(d); // true
DirMatch.matchesAllBelow(d); // false
rust
let d = Glob::new("src/**/*.ts")?.match_dir(b"src");
assert!(!d.matches());
assert!(d.may_match_below());
assert!(!d.matches_all_below());

Spec: GLOB_SPEC §15.1–15.2

A pattern that selects files ​

For an include pattern, the walker wants to know whether a directory is worth entering. It reads may match below: when that is false, nothing under the directory can match, and the subtree is skipped. When matches all below is true, every file below is a result, and the walker may stop testing files one by one.

PatternDirectoryVerdictWalker action
src/**/*.tssrcDescendEnter; test files inside.
src/**/*.tssrc/engineDescendEnter.
src/**/*.tsnode_modulesPrunedSkip the whole subtree.
src/*.tssrcDescendEnter.
src/*.tssrc/aPrunedSkip: * cannot cross the /.
src/** (with dot)srcDescendAllEnter; every file below is a match.
js
const include = compileMatcher(["src/**/*.ts", "docs/**/*.md"]);
for (const dir of ["", "src", "docs/guide", "node_modules"]) {
  DirMatch.mayMatchBelow(include.matchDir(dir)); // true, true, true, false
}

The empty string is the walk root: it always may match below.

A pattern that excludes files ​

For an exclude pattern, the questions turn around. The walker wants to know whether a directory can be dropped whole; that is matches all below. It also wants to know when it can stop testing this pattern under a directory; that is may match below being false.

PatternDirectoryVerdictWalker action
**/node_modules/** (with dot)node_modulesDescendAllEverything below is excluded: skip the directory.
**/node_modules/** (with dot)a/b/node_modulesDescendAllSkip.
**/node_modules/** (with dot)srcDescendEnter; some files below may still be excluded.
**/*.logapp.logDescendAndMatchEnter: the directory matches, the files below need not.
dist/**srcPrunedEnter, and stop testing this exclude below src.

The **/*.log row is the case the three facts exist for. A pattern meant for files can match a directory's own path. That says nothing about the files inside it: app.log/notes.txt does not end in .log. An exclude list must only skip a directory on matches all below, never on matches.

js
const exclude = compileMatcher(["**/node_modules/**", "**/*.log"]);
DirMatch.matchesAllBelow(exclude.matchDir("node_modules")); // true  → skip whole
DirMatch.matchesAllBelow(exclude.matchDir("app.log")); // false → keep walking

The same six verdicts serve both roles

A verdict is a statement about the pattern, not a command to the walker. Pruned from an include means "skip this directory"; Pruned from an exclude means "this exclude needs no more tests here". The facts carry the meaning; the names are only labels.

The dot option never covers a subtree ​

With dot: false, no wildcard may match a name that starts with .. A directory can then always hold a dotfile the pattern does not match, so matches all below is never true. A consumer that skips a directory on matches all below must compile its excludes with dot: true; the globstar walkers default to dot: false, and also prune a directory when an ignore entry ending in / or /** matches it under either setting.

PatternDirectoryOptionsVerdict
**/node_modules/**node_modulesdot: trueDescendAll
**/node_modules/**node_modulesdot: falseDescend
dist/**distdot: trueDescendAll
dist/**distdot: falseDescend

Spec: GLOB_SPEC §15.5

Negated patterns ​

A pattern with a leading ! matches every path its body does not match. What it excludes below a directory cannot be told from the directory itself, so something below may always match; whether the directory itself matches is exact. The verdict is DescendAndMatch or Descend, never a covering one.

js
compileMatcher("!**/*.ts").matchDir("src"); // DirMatch.DescendAndMatch: `src` is not a `.ts` path
compileMatcher("!**/*.ts").matchDir("a.ts"); // DirMatch.Descend

Spec: GLOB_SPEC §15.4

Union of patterns ​

For a matcher built from several patterns, the verdict is computed on the union, not per member. If any member may match below, the union may. "All below" is a property of the whole set, so members that each cover a part can cover together. The examples are on Directory verdicts on a union.

How a path is queried ​

Walkers get directory names from readdir without a trailing separator, and that is the canonical form to ask about: matchDir("src"), not matchDir("src/"), and matchDir("C:") for a drive. The directory path is not normalized; a trailing / asks about that exact byte string, whose children are src//…. The empty string is the root of the walk. The filesystem root / has no slashless form, and matchDir("/") asks about paths below // (/p/** gives Pruned there): ask about "" for it, whose answers hold for every path below.

Static prefixes ​

staticPrefixes() returns the literal path prefixes every match starts with, so a walk can begin there instead of at the root. Each one is the literal head of one expansion of the pattern's braces, up to its last whole segment: src/**/*.ts and docs/**/*.md together give src and docs, {node_modules,packages}/lodash/package.json gives both full paths, and **/*.ts gives the empty prefix, meaning the root. A prefix that a shorter one covers is left out. A very large pattern may give a shorter prefix than its heads, which still holds: the work and the list stay linear in the pattern.

The prefixes are spelled the way the pattern is: with /, and in the pattern's case. With caseInsensitive: true, SRC/*.ts matches src/a.ts but its prefix is SRC, so a walker on a case-sensitive disk finds no such folder; write the prefix in the case the disk uses, or start with a class ([Ss]rc/*.ts) to walk from the root.

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

Spec: GLOB_SPEC §17

Released under the MIT License.