doublestar

doublestar is a Go library that implements globbing and pattern matching for file paths, extending the standard path.Match and filepath.Glob semantics with support for double-star (**) recursive wildcards familiar from Bash’s globstar. Version 4 is a ground-up rewrite built around Go’s io/fs package, letting it glob against any fs.FS implementation — the real filesystem, embed.FS, in-memory filesystems, or remote/virtual ones — rather than being tied to the OS filesystem.

The library exposes drop-in replacements for Match, PathMatch, and Glob, plus a GlobWalk function that streams matches to a callback instead of collecting them all in memory, and a suite of GlobOptions (case-insensitive matching, hidden-file exclusion, symlink handling, fail-on-IO-error behavior) for tuning matching behavior without changing the pattern syntax.

What You Get

• Match() and PathMatch() functions as drop-in replacements for path.Match() and filepath.Match(), with ** support
• Glob() and GlobWalk() for filesystem globbing against any io/fs.FS, including embed.FS
• FilepathGlob() convenience wrapper for direct OS-filesystem globbing
• GlobOption modifiers: WithCaseInsensitive, WithFilesOnly, WithNoFollow, WithNoHidden, WithFailOnIOErrors, WithFailOnPatternNotExist
• SplitPattern() helper for dividing a pattern into a static base path and the remaining glob pattern, useful for initializing scoped fs.FS roots
• ValidatePattern() and ValidatePathPattern() for pre-checking user-supplied patterns before use

Common Use Cases

• Recursively matching source files (e.g. **/*.go) for build tools, linters, or code generators
• Filtering files inside an embed.FS for static asset bundling
• Implementing .gitignore-style or glob-based include/exclude rules in CLI tools
• Validating user-supplied glob patterns in configuration files before running a scan

Under The Hood

Architecture

doublestar is organized as a flat package with clear separation of concerns: match.go implements pure pattern matching (Match/PathMatch) with no filesystem dependency, glob.go implements filesystem globbing built on internal doGlob/doGlobWalk recursion, globwalk.go implements the streaming GlobWalk variant, globoptions.go implements a functional-options pattern (GlobOption) shared by Glob and GlobWalk, utils.go plus platform-specific utils_unix.go/utils_windows.go isolate OS-specific path and file-attribute logic behind build tags, and validate.go implements pattern well-formedness checking shared by both the matching and globbing code paths. Because core matching logic has zero dependency on any filesystem, the only integration point needed to glob a new source (embed.FS, an in-memory filesystem, a virtual filesystem) is the fsys argument passed to Glob/GlobWalk.

Tech Stack

The module targets Go 1.16+ (github.com/bmatcuk/doublestar/v4) and declares zero third-party dependencies — go.mod contains nothing beyond the module directive itself. It is built entirely on the standard library: io/fs for filesystem abstraction, path and path/filepath for separator-aware matching, and errors for sentinel error values. Tooling is plain go test, with CI running on GitHub Actions across ubuntu-latest and windows-latest, using go test -race -coverprofile on Linux and uploading coverage to Codecov. There is no deployment target — the package is distributed via Go modules, with the v4 suffix in the import path following Go’s semantic-import-versioning convention for major-version bumps.

Code Quality

doublestar_test.go is the primary suite at nearly 1,000 lines, using heavily table-driven tests in the idiomatic Go testing package with no external assertion library; globwalk_test.go and platform-specific utils_test.go/utils_unix_test.go/utils_windows_test.go round out coverage. Error handling uses explicit sentinel errors (ErrBadPattern, ErrPatternNotExist) returned directly rather than panics, and *Unvalidated function variants exist specifically so callers can skip re-validation once they’ve already validated a pattern, favoring explicit opt-in over implicit magic. Naming is consistent and idiomatic (exported CamelCase, doc comments preceding every exported symbol), and CI enforces go test -race with tracked coverage on every push and pull request; no linter configuration is checked in.

What Makes It Unique

The library’s defining choice is targeting io/fs.FS rather than the OS filesystem directly — something the standard library’s filepath.Glob() cannot do — which lets callers glob against embed.FS, in-memory filesystems, or any custom fs.FS implementation with the same API. The functional-options GlobOption pattern (WithCaseInsensitive, WithNoHidden, WithFilesOnly, and others) extends matching behavior cleanly without a combinatorial explosion of function variants, and the callback-based GlobWalk API avoids building large in-memory result slices when walking big trees. The public API closely mirrors path.Match/filepath.Glob signatures, keeping the learning curve low for anyone already familiar with Go’s built-in globbing.