Linux	OS X	Windows	Coverage	Downloads

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

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

• Linux + Node: 0.8 - 7.x
• Windows + Node: 0.10 - 7.x, node < 0.10 is not tested due to the lack of support of appveyor.

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.

• Usage
• Guide for 2.x -> 3.x
• Guide for 3.x -> 4.x
• Related Packages
  • glob-gitignore matches files using patterns and filters them according to gitignore rules.

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

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

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

• ignore is a standalone module, and is much simpler so that it could easy work with other programs, unlike isaacs's fstream-ignore which must work with the modules of the fstream family.

• ignore only contains utility methods to filter paths according to the specified ignore rules, so

  • ignore never try to find out ignore rules by traversing directories or fetching from git configurations.
  • ignore don't cares about sub-modules of git projects.

• Exactly according to gitignore man page, fixes some known matching issues of fstream-ignore, such as:

  • '/*.js' should only match 'a.js', but not 'abc/a.js'.
  • '**/foo' should match 'foo' anywhere.
  • Prevent re-including a file if a parent directory of that file is excluded.
  • Handle trailing whitespaces:
    • 'a '(one space) should not match 'a '(two spaces).
    • 'a \ ' matches 'a '
  • All test cases are verified with the result of git check-ignore.

• pattern String|Ignore An ignore pattern string, or the Ignore instance
• patterns Array.<pattern> Array of ignore patterns.

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.

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.

new in 3.2.0

Returns Boolean whether pathname should be ignored.

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

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

• paths Array.<path> The array of pathnames to be filtered.

NOTICE that:

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

// WRONG
ig.ignores('./abc')

// WRONG, for it will never happen.
// If the gitignore rule locates at the root directory,
// `'/abc'` should be changed to `'abc'`.
// ```
// path.relative('/', '/abc')  -> 'abc'
// ```
ig.ignores('/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 git ignore 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'
]

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)
})

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

Returns function(path) the filter function.

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

const ig = ignore({
  ignorecase: false
})

ig.add('*.png')

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

• All options of 2.x are unnecessary and removed, so just remove them.
• ignore() instance is no longer an EventEmitter, and all events are unnecessary and removed.
• .addIgnoreFile() is removed, see the .addIgnoreFile section for details.

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

var ignore = require('ignore/legacy')

• @whitecolor Alex
• @SamyPesse Samy Pessé
• @azproduction Mikhail Davydov
• @TrySound Bogdan Chadkin
• @JanMattner Jan Mattner
• @ntwb Stephen Edgar
• @kasperisager Kasper Isager
• @sandersn Nathan Shively-Sanders