Clarify double-star wildcard matching behavior in pattern documentation

This commit is contained in:
Andrea Mazzoleni 2026-08-26 14:38:06 +02:00
parent 76e8ae2498
commit f9b31db1a7
42 changed files with 561 additions and 525 deletions

View file

@ -1581,20 +1581,19 @@ Pattern
component. This is the standard wildcard behavior familiar from shell
globbing.
The double star `**` is more powerful, it matches any sequence of
characters including directory separators. This allows patterns to match
across multiple directory levels. When `**` appears embedded directly in
a pattern, it can match zero or more characters including slashes between
the surrounding literal text.
The most important use of `**` is in the special form `/**/`. This matches
zero or more complete directory levels, making it possible to match files
at any depth in a directory tree without knowing the exact path structure.
For example, the pattern `src/**/main.js` matches `src/main.js` (skipping
zero directories), `src/ui/main.js` (skipping one directory), and
`src/ui/components/main.js` (skipping two directories).
The double star `**` wildcard matches across directory separators only
when it is adjacent to a directory separator (preceded or followed by a
slash). In this form, it matches zero or more characters across directory
levels. For example, `foo/**/bar` matches `foo/bar`, `foo/a/bar`, and
`foo/a/b/bar`; `**/build` matches `build` and `foo/bar/build`; and
`src/**.js` matches `src/main.js` and `src/ui/components/main.js`.
The standalone form `/**/` is not accepted as a complete pattern.
When `**` is not adjacent to a slash, it behaves like `*` and does not
match directory separators. For example, `**.jpg` matches `photo.jpg`
within the current directory, but does not match `dir/photo.jpg`. Use
`**/*.jpg` for that purpose.
Character classes using square brackets match a single character from a
specified set or range. Like the other single character patterns, they do
not match directory separators. Classes support ranges and negation using
@ -1602,8 +1601,8 @@ Pattern
The fundamental distinction to remember is that `*`, `?`, and character
classes all respect directory boundaries and only match within a single path
component, while `**` is the only pattern that can match across directory
separators.
component, while `**` can match across directory separators only when
adjacent to a slash.
There are four different types of patterns: