ignore

Linux / MacOS / Windows	Coverage	Downloads

ignore

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

ignore is used by eslint, gitbook and many others.

Pay ATTENTION that minimatch (which used by fstream-ignore) does not follow the gitignore spec.

To filter filenames according to a .gitignore file, I recommend this npm package, ignore.

To parse an .npmignore file, you should use minimatch, because an .npmignore file is parsed by npm using minimatch and it does not work in the .gitignore way.

Tested on

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

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.

Table Of Main Contents

Usage
Pathname Conventions
See Also:
- glob-gitignore matches files using patterns and filters them according to gitignore rules.
Upgrade Guide

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?

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.

Methods

.add(pattern: string | Ignore): this

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

.add({pattern: string, mark?: string}): this since 7.0.0

pattern string | Ignore An ignore pattern string, or the Ignore instance
patterns Array<string | Ignore> Array of ignore patterns.
mark? string Pattern mark, which is used to associate the pattern with a certain marker, such as the line no of the .gitignore file. Actually it could be an arbitrary string and is optional.

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.

.ignores(pathname: Pathname): boolean

new in 3.2.0

Returns Boolean whether pathname should be ignored.

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

Please PAY ATTENTION that .ignores() is NOT equivalent to git check-ignore although in most cases they return equivalent results.

However, for the purposes of imitating the behavior of git check-ignore, please use .checkIgnore() instead.

`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.

A . or .. component anywhere else in a Pathname is outside the convention as well, though no error is thrown for it: the check reads how the path starts, so that it costs nothing on a hot path. path.relative() never produces such a component, and one that carries it is not matched the way git matches it — git drops the component from the path first, ignore matches the path as it was given.

// path.relative('/', '/a/./b')  -> 'a/b'

// Right
ignore().add('a/b').ignores('a/b')       // true

// Outside the convention: git matches 'a/b' here and so says true
ignore().add('a/b').ignores('a/./b')     // false

// Outside the convention: git matches 'a' here and so says false
ignore().add('a/.').ignores('a/.')       // true

A rule that matches an ancestor still agrees, since the component makes no difference to it: add('a').ignores('a/./b') is true either way.

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 node-ignore treats

foo as a file
foo/ as a directory

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

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

type Pathname = string

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

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

.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): TestResult

New in 5.0.0

This method is NOT meant for ordinary users or everyday use. If all you need is to tell whether a pathname is ignored, this is not the method you are looking for.

.test() is meant for packages that build upon ignore. Besides whether a pathname is ignored, it tells whether a negative pattern unignored it, which such a package can use to control its own caching, such as what to cache and when a cached result can be reused.

If you only need to know whether a pathname should be ignored, use .ignores() instead. It returns that answer as a boolean, and always agrees with .test(pathname).ignored.

Returns TestResult

// Since 5.0.0
interface TestResult {
  ignored: boolean
  // true if a negative pattern matched the `pathname` itself, and no parent
  //   directory of it is ignored -- see "When both are false" below
  unignored: boolean
  // The `IgnoreRule` which ignores the pathname: the last rule to match, the
  //   one `git check-ignore -v` reports
  rule?: IgnoreRule
}

// Since 7.0.0
interface IgnoreRule {
  // The original pattern
  pattern: string
  // Whether the pattern is a negative pattern
  negative: boolean
  // Which is used for other packages to build things upon `node-ignore`
  mark?: string
}

{ignored: true, unignored: false}: the pathname is ignored
{ignored: false, unignored: true}: a negative pattern matched the pathname itself
{ignored: false, unignored: false}: no rule matched the pathname itself, and no parent directory of it is ignored

When both are `false`

{ignored: false, unignored: false} covers two different situations:

no rule matched the pathname, nor any of its parent directories, or
no rule matched the pathname itself, but one of its parent directories is unignored by a negative pattern: the pathname is unignored indirectly.

unignored stays false in the second case because only ignored passes down from a parent directory. A pathname whose parent directory is ignored is ignored as well — git never re-includes a file whose parent directory is excluded — but one whose parent directory is unignored is decided on its own, by the rules that match the pathname itself.

const ig2 = ignore().add([
  'foo*',
  '!foobar'
])

// The directory `foobar/` is unignored directly, by `!foobar`
ig2.test('foobar/')     // {ignored: false, unignored: true}

// No rule matches `foobar/x.js` itself. It is not ignored only because its
//   parent directory `foobar/` is not, so it is unignored indirectly
ig2.test('foobar/x.js') // {ignored: false, unignored: false}

To tell the two situations apart, test the parent directories of the pathname, each with a trailing slash: the pathname is unignored indirectly if any of them is unignored.

['foobar/'].some(dir => ig2.test(dir).unignored) // true

.checkIgnore(target: string): TestResult

new in 7.0.0

Debugs gitignore / exclude files the way git check-ignore -v does. Usually this method is used for other packages to implement the function of git check-ignore -v upon node-ignore. Apart from the known differences:

ignored is what git check-ignore answers for target.
When ignored is true, rule is the rule git check-ignore -v reports. Its pattern is the pattern as it was added, so trailing spaces that git trims are still there.
When the last pattern to match is a negative one, git check-ignore -v reports it, while .checkIgnore() returns unignored: true and no rule. For a directory passed with a trailing slash, unignored is also true when a negative pattern re-includes the directory itself, which git check-ignore -v does not report.
target string the target to test.

Returns TestResult, the same shape .test() returns, so {ignored: false, unignored: false} carries the same two meanings here.

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

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

if (ignored) {
  console.log(`.gitignore:${rule.mark}:${rule.pattern} foo/`)
}

// .gitignore:60:foo/* foo/

Please pay attention that this method does not have a strong built-in cache mechanism.

The purpose of introducing this method is to make it possible to implement the git check-ignore command in JavaScript based on node-ignore.

So do not use this method in those situations where performance is extremely important.

static `isPathValid(pathname): boolean` since 5.0.0

Check whether the pathname is an valid path.relative()d path according to the convention.

This method is NOT used to check if an ignore pattern is valid.

import {isPathValid} from 'ignore'

isPathValid('./foo')  // false

.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.

ignore(options)

`options.ignorecase` since 4.0.0

Similar to 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

`options.ignoreCase?: boolean` since 5.2.0

Which is an alternative to options.ignoreCase

`options.allowRelativePaths?: boolean` since 5.2.0

This option brings backward compatibility with projects which based on ignore@4.x. If options.allowRelativePaths is true, ignore will not check whether the given path to be tested is path.relative()d.

However, passing a relative path, such as './foo' or '../foo', to test if it is ignored or not is not a good practise, which might lead to unexpected behavior

ignore({
  allowRelativePaths: true
}).ignores('../foo/bar.js') // And it will not throw

Upgrade Guide

Known differences from `git`

ignore aims to behave exactly like git check-ignore, and its test suite verifies every fixture against the real git binary. A few divergences are deliberate or inherited from how JavaScript differs from C. They are listed here so you do not have to discover them in production.

Characters, not bytes

git matches patterns against the UTF-8 bytes of a path; JavaScript strings are sequences of UTF-16 code units, and ignore matches those. The two agree on ASCII and disagree on the width of everything else:

// git needs two '?' to match 'é' (two bytes); ignore needs one:
ignore().add('x?y').ignores('xéy')    // true;  git: false

// a range cannot span multi-byte characters in git at all:
ignore().add('m[À-È]n').ignores('mÁn') // true;  git: false

With ignorecase enabled, git folds case for ASCII only, while JavaScript's i flag folds Unicode — so É.txt ignores é.txt here and not in git. For ASCII paths and patterns there is no difference.

`ignorecase` defaults to `true`

git on a case-sensitive filesystem (production Linux) is case-sensitive. ignore is case-insensitive unless you pass ignorecase: false. If your code runs against a real repository, pass the value of the repository's core.ignorecase explicitly.

A run of asterisks

git reads a run of two or more asterisks as a globstar whenever the run fills a path segment: it starts the pattern or follows a /, and it ends the pattern or comes before a /. ignore does the same, so ***/foo, a/*** and a/***/b behave exactly as **/foo, a/** and a/**/b.

git takes two more cases as a globstar, and ignore does not:

A run right after a literal prefix, as in a**/b or a***/b. Before matching, git strips the part of a pattern that holds no wildcard, and the run then starts what is left. gitignore(5) lists the positions where ** is special and calls every other run "regular asterisks", which is what ignore does here.
A run next to an escaped slash, as in **\/b or x\/**/b.

ignore().add('a**/b').ignores('axy/z/b')   // false;  git: true
ignore().add('**\\/b').ignores('x/y/b')    // false;  git: true
ignore().add('x\\/**/b').ignores('x/y/z/b') // false;  git: true

To get a globstar in either case, give the run a segment of its own, such as a*/**/b.

`checkIgnore()` and a directory passed with a trailing slash

.checkIgnore('a/') follows git check-ignore -- a/, which differs from a traversal. If the directory a is excluded, by itself or by an ancestor, that is the answer. Otherwise git matches the literal string a/, where the basename is empty: a/* and a/** match a/ itself, and a pattern like !a or !a/ does not. .ignores('a/') and .test('a/') keep the traversal semantics, where a/** does not exclude the directory a.

Upgrade 4.x -> 5.x

Since 5.0.0, if an invalid Pathname passed into ig.ignores(), an error will be thrown, unless options.allowRelative = true is passed to the Ignore factory.

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(isPathValid)

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

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.

Collaborators

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

Name		Name	Last commit message	Last commit date
.github		.github
benchmark		benchmark
compat		compat
test		test
.babelrc		.babelrc
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
LICENSE-MIT		LICENSE-MIT
README.md		README.md
index.d.ts		index.d.ts
index.js		index.js
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

ignore

Tested on

Table Of Main Contents

Install

Usage

Filter the given paths

As the filter function

Win32 paths will be handled

Why another ignore?

Methods

.add(pattern: string | Ignore): this

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

.add({pattern: string, mark?: string}): this since 7.0.0

.ignores(pathname: Pathname): boolean

Pathname Conventions:

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

2. filenames and dirnames

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

.createFilter()

.test(pathname: Pathname): TestResult

When both are false

.checkIgnore(target: string): TestResult

static isPathValid(pathname): boolean since 5.0.0

.addIgnoreFile(path)

ignore(options)

options.ignorecase since 4.0.0

options.ignoreCase?: boolean since 5.2.0

options.allowRelativePaths?: boolean since 5.2.0

Upgrade Guide

Known differences from git

Characters, not bytes

ignorecase defaults to true

A run of asterisks

checkIgnore() and a directory passed with a trailing slash

Upgrade 4.x -> 5.x

Upgrade 3.x -> 4.x

Upgrade 2.x -> 3.x

Collaborators

About

Topics

Resources

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

`Pathname` Conventions:

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

When both are `false`

static `isPathValid(pathname): boolean` since 5.0.0

`options.ignorecase` since 4.0.0

`options.ignoreCase?: boolean` since 5.2.0

`options.allowRelativePaths?: boolean` since 5.2.0

Known differences from `git`

`ignorecase` defaults to `true`

`checkIgnore()` and a directory passed with a trailing slash