Add includeChildMatches: false option

This does a (best effort) attempt to ignore all *subsequent* matches
that are a descendant of a previous match.

Note the caveat in the docs, though. It will only ignore what it knows
about. There's no post-hoc evaluation to only return the shortest
results in cases where a deeper match is encountered before its
shallower parent.

Author: isaacs

.tshy/build.json

@@ -2,7 +2,6 @@
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "rootDir": "../src",
-    "target": "es2022",
     "module": "nodenext",
     "moduleResolution": "nodenext"
   }

README.md

@@ -593,6 +593,48 @@ share the previously loaded cache.
   explicitly, then any provided `scurry` object must match this
   setting.
 
+- `includeChildMatches` boolean, default `true`. Do not match any
+  children of any matches. For example, the pattern `**\/foo`
+  would match `a/foo`, but not `a/foo/b/foo` in this mode.
+
+  This is especially useful for cases like "find all
+  `node_modules` folders, but not the ones in `node_modules`".
+
+  In order to support this, the `Ignore` implementation must
+  support an `add(pattern: string)` method. If using the default
+  `Ignore` class, then this is fine, but if this is set to
+  `false`, and a custom `Ignore` is provided that does not have
+  an `add()` method, then it will throw an error.
+
+  **Caveat** It *only* ignores matches that would be a descendant
+  of a previous match, and only if that descendant is matched
+  *after* the ancestor is encountered. Since the file system walk
+  happens in indeterminate order, it's possible that a match will
+  already be added before its ancestor, if multiple or braced
+  patterns are used.
+
+  For example:
+
+  ```js
+  const results = await glob([
+    // likely to match first, since it's just a stat
+    'a/b/c/d/e/f',
+
+    // this pattern is more complicated! It must to various readdir()
+    // calls and test the results against a regular expression, and that
+    // is certainly going to take a little bit longer.
+    //
+    // So, later on, it encounters a match at 'a/b/c/d/e', but it's too
+    // late to ignore a/b/c/d/e/f, because it's already been emitted.
+    'a/[bdf]/?/[a-z]/*',
+  ], { includeChildMatches: false })
+  ```
+
+  It's best to only set this to `false` if you can be reasonably
+  sure that no components of the pattern will potentially match
+  one another's file system descendants, or if the occasional
+  included child entry will not cause problems.
+
 ## Glob Primer
 
 Much more information about glob pattern expansion can be found