ignore

To use ignore in your project, install it using npm:

npm i ignore

Starting from version 5.0.0, passing an invalid Pathname to .ignores() will throw an error. To prevent this, you can either pass options.allowRelative = true to the Ignore factory or manually validate paths using the isPathValid utility introduced in 5.0.0.

Invalid pathnames include empty strings, non-string values (like false), relative paths starting with .., or the current directory ..

import {isPathValid} from 'ignore'

const paths = [
  '',
  false,
  '../foo',
  '.',
  'foo' // valid
].filter(isPathValid)

// Now safe to use with your ignore instance
ig.filter(paths)

Version 4.0.0 dropped support for Node.js versions earlier than 6. If you must use ignore in a Node.js environment older than version 6, use the legacy entry point:

var ignore = require('ignore/legacy')

Several breaking changes occurred in version 3.0.0:

• All options from 2.x were removed; they are no longer necessary.
• The ignore() instance is no longer an EventEmitter; all event-based logic was removed.
• The .addIgnoreFile() method was removed. Use the .add() method instead to add patterns.

In version 5.0.0, the following methods were standardized to follow specific return value conventions for Pathname handling:

• .ignores(pathname: Pathname): boolean
• .filter(pathnames: Array<Pathname>): Array<Pathname>
• .createFilter(): (pathname: Pathname) => boolean
• .test(pathname: Pathname): {ignored: boolean, unignored: boolean}

Users are responsible for converting or filtering invalid pathnames before passing them to these methods.

You can initialize an ignore instance, add patterns (including negative patterns to unignore files), and then filter paths or check if specific paths are ignored.

Note: ignore follows the .gitignore spec 2.22.1. If you need to parse .npmignore files, use minimatch instead, as npm uses minimatch for .npmignore and it does not follow the gitignore spec.

import ignore from 'ignore'
const ig = ignore().add(['.abc/*', '!.abc/d/'])

const paths = [
  '.abc/a.js',    // filtered out
  '.abc/d/e.js'   // included
]

ig.filter(paths)        // ['.abc/d/e.js']
ig.ignores('.abc/a.js') // true

By default, ignore is case-insensitive (matching git-config behavior). You can change this via the constructor options.

Options:

• ignorecase (v4.0.0+): boolean. Set to false for case-sensitive matching. (Note: ignoreCase is an alias since v5.2.0).
• allowRelativePaths (v5.2.0+): boolean. If true, it disables the check that ensures paths are path.relative()d. This is provided for backward compatibility with v4.x, but using ./foo or ../foo is not recommended.

// Case-sensitive matching
const ig = ignore({ ignorecase: false })
ig.add('*.png')
ig.ignores('image.PNG') // false

// Allowing non-standard relative paths
const igRel = ignore({ allowRelativePaths: true })
ig.ignores('../foo/bar.js') // true (will not throw)

To use node-ignore, call the default export (the factory function) with an optional configuration object. This returns an Ignore instance used to manage ignore patterns and test paths.

Configuration Options:

• ignorecase (boolean, default: true): Whether pattern matching should be case-insensitive.
• allowRelativePaths (boolean, default: false): If false, the library will throw errors if paths are not relative (e.g., absolute paths or paths starting with . or ..).

const factory = require('node-ignore');

// Default configuration (case-insensitive, strict relative paths)
const ignore = factory();

// Custom configuration
const ignoreCustom = factory({
  ignorecase: false,
  allowRelativePaths: true
});

Instead of calling .filter() manually, you can use .createFilter() to generate a function compatible with Array.prototype.filter.

const ig = ignore().add(['node_modules/'])
const paths = ['index.js', 'node_modules/lodash/index.js']

// Use the created filter function directly in Array.filter
const filtered = paths.filter(ig.createFilter())
// Result: ['index.js']

Introduced in v7.0.0, .checkIgnore(target) is designed to mimic git check-ignore -v. It returns a TestResult that includes the rule details, making it useful for debugging or implementing git-like CLI tools.

Warning: This method does not have a strong built-in cache mechanism. Avoid using it in performance-critical loops.

const ig = ignore().add({
  pattern: 'foo/*',
  mark: '60'
})

const { ignored, rule } = ig.checkIgnore('foo/bar.js')

if (ignored) {
  // Example output format mimicking git check-ignore -v
  console.log(`.gitignore:${rule.mark}:${rule.pattern} foo/bar.js`)
}

A static method used to check if a given pathname follows the required path.relative() convention. This does not validate if the ignore pattern itself is valid.

import { isPathValid } from 'ignore'

isPathValid('abc/def')   // true
isPathValid('./abc/def') // false