README

Linux

OS X

Windows

Coverage

Downloads </thead><tbody>

</tbody>

# 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

- pattern `String | Ignore` An ignore pattern string, or the `Ignore` instance
- patterns `Array<String | Ignore>` 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.

## <strike>.addIgnoreFile(path)</strike>

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.

- paths `Array.<Pathname>` The array of `pathname`s to be filtered.

### <tt>Pathname</tt> Conventions:

#### 1. <tt>Pathname</tt> should be a <tt>path.relative()</tt>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:
```js
[
'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
}

- `{ignored: true, unignored: false}`: the `pathname` is ignored
- `{ignored: false, unignored: true}`: the `pathname` is unignored
- `{ignored: false, unignored: false}`: the `pathname` is never matched by any ignore rules.

## <tt>options.ignorecase</tt> 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 <tt>ignore.isPathValid(pathname): boolean</tt> 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.

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

- 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