ignore

ignore is a manager, filter and parser which implemented in pure JavaScript according to the .gitignore spec.

ignore is used by eslint, gitbook and many others.

Pay attention that minimatch does not work in the gitignore way. To filter filenames according to .gitignore file, I recommend this module.

Tested on

ignore is fully tested, and has more than five hundreds of unit tests.

Actually, ignore does not rely on any versions of node specially.

Since 4.0.0, ignore will no longer support node < 6 by default, to use in node < 6, require('ignore/legacy'). For details, see CHANGELOG.

Table Of Main Contents

Install

npm i ignore

Usage

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

Filter the given paths

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

As the filter function

paths.filter(ig.createFilter()); // ['.abc/d/e.js']

Win32 paths will be handled

ig.filter(['.abc\\a.js', '.abc\\d\\e.js'])
// if the code above runs on windows, the result will be
// ['.abc\\d\\e.js']

Why another ignore?

Methods

.add(pattern: string | Ignore): this

.add(patterns: Array<string | Ignore>): this

Adds a rule or several rules to the current manager.

Returns this

Notice that a line starting with '#'(hash) is treated as a comment. Put a backslash ('\') in front of the first hash for patterns that begin with a hash, if you want to ignore a file with a hash at the beginning of the filename.

ignore().add('#abc').ignores('#abc')    // false
ignore().add('\#abc').ignores('#abc')   // true

pattern could either be a line of ignore pattern or a string of multiple ignore patterns, which means we could just ignore().add() the content of a ignore file:

ignore()
.add(fs.readFileSync(filenameOfGitignore).toString())
.filter(filenames)

pattern could also be an ignore instance, so that we could easily inherit the rules of another Ignore instance.

.addIgnoreFile(path)

REMOVED in 3.x for now.

To upgrade ignore@2.x up to 3.x, use

import fs from 'fs'

if (fs.existsSync(filename)) {
  ignore().add(fs.readFileSync(filename).toString())
}

instead.

.filter(paths: Array<Pathname>): Array<Pathname>

type Pathname = string

Filters the given array of pathnames, and returns the filtered array.

Pathname Conventions:

1. Pathname should be a path.relative()d pathname

Pathname should be a string that have been path.join()ed, or the return value of path.relative() to the current directory,

// WRONG, an error will be thrown
ig.ignores('./abc')

// WRONG, for it will never happen, and an error will be thrown
// If the gitignore rule locates at the root directory,
// `'/abc'` should be changed to `'abc'`.
// ```
// path.relative('/', '/abc')  -> 'abc'
// ```
ig.ignores('/abc')

// WRONG, that it is an absolute path on Windows, an error will be thrown
ig.ignores('C:\\abc')

// Right
ig.ignores('abc')

// Right
ig.ignores(path.join('./abc'))  // path.join('./abc') -> 'abc'

In other words, each Pathname here should be a relative path to the directory of the gitignore rules.

Suppose the dir structure is:

/path/to/your/repo
    |-- a
    |   |-- a.js
    |
    |-- .b
    |
    |-- .c
         |-- .DS_store

Then the paths might be like this:

[
  'a/a.js'
  '.b',
  '.c/.DS_store'
]

2. filenames and dirnames

node-ignore does NO fs.stat during path matching, so for the example below:

// First, we add a ignore pattern to ignore a directory
ig.add('config/')

// `ig` does NOT know if 'config', in the real world,
//   is a normal file, directory or something.

ig.ignores('config')
// `ig` treats `config` as a file, so it returns `false`

ig.ignores('config/')
// returns `true`

Specially for people who develop some library based on node-ignore, it is important to understand that.

Usually, you could use glob with option.mark = true to fetch the structure of the current directory:

import glob from 'glob'

glob('**', {
  // Adds a / character to directory matches.
  mark: true
}, (err, files) => {
  if (err) {
    return console.error(err)
  }

  let filtered = ignore().add(patterns).filter(files)
  console.log(filtered)
})

.ignores(pathname: Pathname): boolean

new in 3.2.0

Returns Boolean whether pathname should be ignored.

ig.ignores('.abc/a.js')    // true

.createFilter()

Creates a filter function which could filter an array of paths with Array.prototype.filter.

Returns function(path) the filter function.

.test(pathname: Pathname) since 5.0.0

Returns TestResult

interface TestResult {
  ignored: boolean
  // true if the `pathname` is finally unignored by some negative pattern
  unignored: boolean
}

options.ignorecase since 4.0.0

Similar as the core.ignorecase option of git-config, node-ignore will be case insensitive if options.ignorecase is set to true (the default value), otherwise case sensitive.

const ig = ignore({
  ignorecase: false
})

ig.add('*.png')

ig.ignores('*.PNG')  // false

static ignore.isPathValid(pathname): boolean since 5.0.0

Check whether the pathname is valid according to the convention.

ignore.isPathValid('./foo')  // false

Upgrade Guide

Upgrade 4.x -> 5.x

Since 5.0.0, if an invalid Pathname passed into ig.ignores(), an error will be thrown, while ignore < 5.0.0 did not make sure what the return value was, as well as

.ignores(pathname: Pathname): boolean

.filter(pathnames: Array<Pathname>): Array<Pathname>

.createFilter(): (pathname: Pathname) => boolean

.test(pathname: Pathname): {ignored: boolean, unignored: boolean}

See the convention here for details.

If there are invalid pathnames, the conversion and filtration should be done by users.

import {isPathValid} from 'ignore' // introduced in 5.0.0

const paths = [
  // invalid
  //////////////////
  '',
  false,
  '../foo',
  '.',
  //////////////////

  // valid
  'foo'
]
.filter(isValidPath)

ig.filter(paths)

Upgrade 3.x -> 4.x

Since 4.0.0, ignore will no longer support node < 6, to use ignore in node < 6:

var ignore = require('ignore/legacy')

Upgrade 2.x -> 3.x

Collaborators