cspell-gitignore

cspell-gitignore

A library to assist reading and filtering out files matching glob patterns found in .gitignore files.

Install

npm install -S cspell-gitignore

Usage

import { GitIgnore, findRepoRoot } from 'cspell-gitignore';

// ...

const cwd = process.cwd();
const root = (await findRepoRoot(cwd)) || cwd;
const gitIgnore = new GitIgnore([root]);

const allFiles = glob('**');

const files = await gitIgnore.filterOutIgnored(allFiles);

Logic

• For each file, search for the .gitignore files in the directory hierarchy.
• Ignore any files that match the globs found in the .gitignore files.

The .gitignore globs are evaluated from highest to lowest, matching the git behavior.

To prevent searching higher in the directory hierarchy, specify roots:

const gitIgnore = new GitIgnore([process.cwd()]);

cspell-gitignore CLI

cspell-gitignore provides a simple cli for debugging .gitignore issues.

In most cases it should provide the same output as git check-ignore.

Usage

Usage cspell-gitignore [options] <files>

Check files against .gitignore
Compare against git check-ignore -v -n <files>

Options:
  -r, --root   Add a root to prevent searching for .gitignore files above the root if the file is under the root.
               This option can be used multiple times to add multiple roots. The default root is the current
               repository root determined by the `.git` directory.

Example:
  cspell-gitignore README.md
  cspell-gitignore -r . node_modules

Example:

$ cspell-gitignore -r . node_modules
.gitignore:58:node_modules/       node_modules

Changelog

<small>8.17.3 (2025-01-28)</small>

• chore: fix labeler (ea51ed4)