globby

globby wraps fast-glob with a batch of ergonomic conveniences: a promise-based API, support for multiple patterns in a single call, negated and negation-only patterns, automatic expansion of directory patterns into recursive globs, and native .gitignore-aware filtering. It is one of the most widely used file-globbing libraries in the Node.js ecosystem, relied on by build tools, linters, and CLIs to resolve file lists from user-supplied patterns.

When gitignore mode is enabled, globby reads .gitignore files from the working directory up through the repository root before globbing, and proves which ignored directories can be safely skipped during traversal (rather than enumerated and filtered afterward), so large ignored trees like node_modules don’t slow down the scan while still matching Git’s exact ignore semantics, including negation patterns.

What You Get

• A globby(patterns, options?) promise API returning matched file paths, plus a synchronous globbySync variant
• Multiple and negated pattern support in a single call (['foo*', '!foobar'])
• Automatic directory expansion (foo becomes foo/**/*) configurable via expandDirectories
• Native .gitignore support that walks parent directories to the repo root and matches Git’s exact ignore semantics
• convertPathToPattern() for safely turning a filesystem path into a valid glob pattern (handling Windows backslashes)
• URL support as a cwd value alongside plain string paths

Common Use Cases

• Resolving a build tool’s or bundler’s input file list from user-configured glob patterns
• Writing a lint/format CLI that needs to skip .gitignored files automatically without re-implementing Git’s ignore rules
• Expanding a directory argument (src) into every file beneath it as part of a CLI’s file-discovery step
• Finding files to process in a Gulp-style task pipeline where multiple glob patterns need combining with exclusions

Under The Hood

Architecture: index.js (707 lines) is the core entrypoint, translating globby’s higher-level options (expandDirectories, gitignore, onlyFiles, etc.) into one or more fast-glob calls, then merging/deduplicating the resulting path streams (via @sindresorhus/merge-streams for the streaming variant). ignore.js (1016 lines) is the largest module and implements gitignore-aware filtering: it discovers .gitignore files from the cwd up to the detected repository root, compiles them with the ignore package, and — critically for performance — proves which directories are provably fully ignored (no negation pattern could re-include their contents) so those directories are excluded from fast-glob’s own traversal instead of being walked and filtered after the fact. utilities.js (554 lines) holds shared helpers like directory-expansion logic and path/pattern normalization (including convertPathToPattern). Tech Stack: Pure ESM (type: module, Node.js >=20 required), built on fast-glob for the underlying matching engine, ignore for gitignore-pattern compilation, @sindresorhus/merge-streams for combining async iterables, is-path-inside and slash/unicorn-magic for path handling; devDependencies show a benchmark harness (bench.js) that compares against glob-stream and a main-branch fork of itself, plus xo (linting), ava (tests), and tsd (type-definition tests). Code Quality: The tests/ directory has ten focused test files (globby.js, ignore.js, gitignore-comprehensive.js, gitignore-vs-git.js, global-gitignore.js, global-gitignore-custom-fs.js, parent-directory-patterns.js, convert-path-to-pattern.js, generate-glob-tasks.js, utilities.js) that specifically stress-test the gitignore-matching-Git-behavior guarantee — including a dedicated gitignore-vs-git.js file that appears to diff globby’s ignore behavior directly against real Git output — which is a strong quality signal for a feature whose entire value proposition is ‘matches Git exactly.’ TypeScript types are validated via tsd against index.test-d.ts. API Design: The single globby(patterns, options) promise entrypoint (with a synchronous twin) covers the vast majority of use cases with no configuration required for the common case, while options like expandDirectories and gitignore are opt-in booleans rather than required setup — the README’s copy-pasteable three-line usage example demonstrates the entire happy path, and pattern negation reuses familiar glob syntax (!pattern) rather than a separate exclude option.