ignore

ignore is a standalone library that implements the .gitignore matching spec in pure JavaScript, with no dependency on the filesystem or on git itself. You feed it a set of pattern strings — the same syntax used in .gitignore files, including negation, directory-only rules, and glob wildcards — and it tells you which of an array of pathnames should be excluded, matching git check-ignore output.

Because it never touches the disk or shells out to git, ignore works identically in Node.js scripts, bundlers, and any environment where you already have a list of candidate paths (for example, from glob) and need to filter them the way git, ESLint, or npm’s .npmignore-adjacent tooling would. It is the pattern-matching engine underneath several well-known JavaScript dev tools.

What You Get

• An Ignore manager built with ignore() that accepts one or many patterns via .add(), including the full text of a .gitignore file at once
• .filter(paths) and .createFilter() to filter an array of pathnames or produce an Array.prototype.filter-compatible predicate
• .ignores(pathname) for a simple boolean check and .test(pathname) for a detailed {ignored, unignored, rule} result
• .checkIgnore(pathname), a git check-ignore -v-equivalent debug method that reports which specific rule matched
• Correct handling of Windows-style backslash paths, case-insensitive matching options, and pattern mark metadata for tracing a rule back to its source line
• Bundled TypeScript type definitions (index.d.ts) with no separate @types package needed

Common Use Cases

• Filtering a file list produced by glob or fast-glob down to only the files a tool should actually process, honoring the project’s .gitignore
• Implementing .eslintignore/.prettierignore-style ignore-file support inside a custom linter, formatter, or build tool
• Re-implementing git check-ignore behavior in JavaScript for editors, file watchers, or CI tooling that needs to explain why a path is excluded
• Building higher-level utilities (like glob-gitignore) that combine glob matching with gitignore-aware filtering

Under The Hood

Architecture — The whole library lives in a single index.js (~790 lines, no runtime dependencies) built around three classes: IgnoreRule compiles one gitignore pattern into a lazily-built RegExp (separate regexes for plain ignores() checks versus checkIgnore() debug checks), RuleManager accumulates IgnoreRule instances and exposes .test(path), and Ignore is the public-facing manager returned by the ignore() factory, wrapping a RuleManager per case-sensitivity mode. Pattern compilation walks the raw string character-by-character (makeRegexPrefix) to translate gitignore glob syntax — **, single *, character ranges, escaped !/# — into an equivalent regex fragment, so matching at query time is just a regex test rather than repeated string parsing.

Tech Stack — Pure JavaScript (95% JS, 5% TypeScript in the bundled index.d.ts) with zero production dependencies. The build pipeline uses Babel (@babel/cli/@babel/preset-env) to emit a legacy.js for pre-ES6 Node targets, ESLint (eslint-config-ostai) for linting, and tap for the test runner. TypeScript consumers get types directly from the shipped .d.ts file — no separate @types/ignore package exists or is needed.

Code Quality — The test suite spans three files (ignore.test.js, others.test.js, git-check-ignore.test.js, ~560 lines) plus a fixtures/ directory, and CI (.github/workflows/nodejs.yml) runs the full suite across Ubuntu, Windows, and macOS on Node 20, plus dedicated test:ts and test:16 jobs for module-resolution edge cases (CJS/ESM/Node16). The README states results are cross-checked against real git check-ignore output for correctness, and the project maintains its own CHANGELOG.md with explicit upgrade guides between major versions (4.x→5.x, etc.).

API Design — The API is deliberately minimal: ignore().add(patterns) returns this for chaining, and querying is a choice between .ignores() (boolean), .filter()/.createFilter() (array/predicate), .test() (structured result), and .checkIgnore() (git-parity debug result with the matching rule). Getting started requires no configuration — ignore().add(['*.log']).ignores('debug.log') is a complete example — though the strict path.relative()-only pathname convention (throwing on ./foo or absolute paths unless allowRelativePaths is set) is a sharp edge documented prominently in the README to head off the most common misuse.