glob

gobwas/glob gives Go programs shell-style glob matching (*, **, ?, character classes, and {a,b} alternation) without paying the cost of a general-purpose regular-expression engine every time a pattern is evaluated. A pattern is compiled once with Compile or MustCompile into a *Pattern, and every subsequent Match call walks a pre-built tree of matcher nodes instead of re-parsing the pattern text.

The compiler recognizes common pattern shapes — literals, prefixes, suffixes, and substrings — and specializes them into plain string-comparison matchers, falling back to a backtracking engine only for the patterns that actually need it. The result is a library that reports itself as safe for concurrent use and allocation-free on the match path, with correctness checked by differential fuzzing against the standard regexp package.

It is a small, dependency-free building block rather than a framework: applications reach for it wherever they need to test a string against a wildcard-style pattern — matching hostnames, file paths, config keys, or CLI arguments — without shelling out to filepath.Match or compiling a full regular expression.

What You Get

• Compile / MustCompile to turn a pattern string into a reusable *Pattern, with configurable separator runes
• Full glob syntax: *, **, ?, [abc]/[!abc]/[a-c] character classes, and {a,b,c} alternation
• *SyntaxError with a byte offset and reason for malformed patterns, suitable for pointing at the exact failure location
• QuoteMeta to escape glob metacharacters in a literal string before compiling it as a pattern
• Pattern.String() and Pattern.Separators() to introspect a compiled pattern, mirroring regexp.Regexp’s API shape
• Compile-time specialization of literal, prefix, suffix, and substring patterns into plain string comparisons instead of backtracking

Common Use Cases

• Hostname/domain matching - matching request hosts or origins against wildcard rules, e.g. *.example.com
• File path filtering - deciding which files a build tool, linter, or watcher should include or ignore
• Config key matching - matching structured keys or route patterns against user-supplied wildcard rules
• Allow/deny list evaluation - checking an input string against a set of glob-style permission or filter rules at request time

Under The Hood

Architecture Compilation (compile in parse.go) uses a stack-based expression-parsing scheme: a leaf token — literal text, ?, *, **, or a [...] class — pushes a matcher onto an operand stack, while { and , push operators that later collapse into multiMatcher/altMatcher nodes once the matching } is seen. Once the tree is built, simplify and specialize walk it to fold sequences and recognize literal/prefix/suffix/substring shapes, replacing generic backtracking nodes with direct string-comparison matchers (textMatcher, prefixMatcher, etc. in match.go) wherever possible. A Pattern also records precomputed match preconditions — minLen and a required suffix — so Match can reject an obvious mismatch in O(1) before walking the tree at all; these are computed only for the subset of patterns that still need backtracking state (needsState), since a fully specialized pattern already performs the same checks inline. Pattern.Match (glob.go/match.go) then either runs a plain call chain for stateless patterns or a checkpointed backtracking walk (matchContext/matchState, with a sync.Pool-style acquireState/releaseState pair) for patterns that need to explore alternatives, such as nested {...} groups combined with wildcards.

Tech Stack The module (module github.com/gobwas/glob, go 1.22.0) has no runtime dependencies outside the Go standard library. It is organized as a small set of top-level files — glob.go for the public API, parse.go for compilation, match.go for the matcher tree and matching logic — plus an internal syntax package (syntax/lexer.go) that tokenizes pattern text, and an internal/debug package that exposes a hidden -v-style tree dump used only by the in-repo cmd/globtest developer tool, without widening the public API surface.

Code Quality Testing is extensive and multi-layered: glob_test.go and issues_test.go cover pattern syntax and regression cases, syntax/lexer_test.go covers the tokenizer in isolation, and fuzz_test.go implements a differential fuzz test (FuzzMatchRegexp) that compares glob’s matching behavior against Go’s own regexp package on generated inputs, with a checked-in seed corpus under testdata/fuzz. CI (.github/workflows/ci.yml) runs gofmt -l, go vet, go test -race, and a 30-second fuzz smoke test on every push and PR across two Go versions (oldstable, stable), and a separate nightly workflow runs a longer scheduled fuzz job. Errors are surfaced through a typed *SyntaxError rather than opaque strings, and exported types carry doc comments written in the modern [Identifier]-link Go doc-comment style.

What Makes It Unique Rather than treating every glob as a generic pattern to be walked character-by-character, the compiler classifies patterns by shape at compile time and downgrades as many of them as possible to direct string operations (strings.HasPrefix/HasSuffix/Contains-equivalent matchers), reserving the backtracking engine for patterns that genuinely require it (nested alternation combined with wildcards). Combined with the O(1) minLen/suffix precondition check and pooled backtracking state, this gives it measured multi-x speedups over equivalent anchored regexp patterns in its own benchmarks, while the differential fuzz harness against regexp gives an unusually strong correctness guarantee for a hand-written matching engine.