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:
| Fact | Question | Which way it errs |
|---|---|---|
matches | Does d itself match, exactly as a file path would? | Exact. |
may match below | Could some path d/… match? | false is a guarantee; true may be cautious. |
matches all below | Does 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:
| Verdict | matches | may match below | matches all below | Example |
|---|---|---|---|---|
Pruned | no | no | no | src/**/*.ts against lib |
Match | yes | no | no | src against src |
Descend | no | yes | no | src/**/*.ts against src |
DescendAndMatch | yes | yes | no | src{,/**/*.ts} against src |
DescendAll | no | yes | yes | dist/** against dist (with dot) |
DescendAllAndMatch | yes | yes | yes | ** 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:
import { compileMatcher, DirMatch } from "@globstar/core";
const d = compileMatcher("src/**/*.ts").matchDir("src");
DirMatch.matches(d); // false
DirMatch.mayMatchBelow(d); // true
DirMatch.matchesAllBelow(d); // falselet 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.
| Pattern | Directory | Verdict | Walker action |
|---|---|---|---|
src/**/*.ts | src | Descend | Enter; test files inside. |
src/**/*.ts | src/engine | Descend | Enter. |
src/**/*.ts | node_modules | Pruned | Skip the whole subtree. |
src/*.ts | src | Descend | Enter. |
src/*.ts | src/a | Pruned | Skip: * cannot cross the /. |
src/** (with dot) | src | DescendAll | Enter; every file below is a match. |
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.
| Pattern | Directory | Verdict | Walker action |
|---|---|---|---|
**/node_modules/** (with dot) | node_modules | DescendAll | Everything below is excluded: skip the directory. |
**/node_modules/** (with dot) | a/b/node_modules | DescendAll | Skip. |
**/node_modules/** (with dot) | src | Descend | Enter; some files below may still be excluded. |
**/*.log | app.log | DescendAndMatch | Enter: the directory matches, the files below need not. |
dist/** | src | Pruned | Enter, 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.
const exclude = compileMatcher(["**/node_modules/**", "**/*.log"]);
DirMatch.matchesAllBelow(exclude.matchDir("node_modules")); // true → skip whole
DirMatch.matchesAllBelow(exclude.matchDir("app.log")); // false → keep walkingThe 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.
| Pattern | Directory | Options | Verdict |
|---|---|---|---|
**/node_modules/** | node_modules | dot: true | DescendAll |
**/node_modules/** | node_modules | dot: false | Descend |
dist/** | dist | dot: true | DescendAll |
dist/** | dist | dot: false | Descend |
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.
compileMatcher("!**/*.ts").matchDir("src"); // DirMatch.DescendAndMatch: `src` is not a `.ts` path
compileMatcher("!**/*.ts").matchDir("a.ts"); // DirMatch.DescendSpec: 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.
compileMatcher(["src/**/*.ts", "docs/**/*.md"]).staticPrefixes(); // [src, docs] as Uint8ArraySpec: GLOB_SPEC §17