10 <td colspan="2" align="center">
11 <a href="https://travis-ci.org/kaelzhang/node-ignore">
13 src="https://travis-ci.org/kaelzhang/node-ignore.svg?branch=master"
14 alt="Build Status" /></a>
17 <a href="https://ci.appveyor.com/project/kaelzhang/node-ignore">
19 src="https://ci.appveyor.com/api/projects/status/github/kaelzhang/node-ignore?branch=master&svg=true"
20 alt="Windows Build Status" /></a>
23 <a href="https://codecov.io/gh/kaelzhang/node-ignore">
25 src="https://codecov.io/gh/kaelzhang/node-ignore/branch/master/graph/badge.svg"
26 alt="Coverage Status" /></a>
29 <a href="https://www.npmjs.org/package/ignore">
31 src="http://img.shields.io/npm/dm/ignore.svg"
32 alt="npm module downloads per month" /></a>
38 `ignore` is a manager, filter and parser which implemented in pure JavaScript according to the .gitignore [spec](http://git-scm.com/docs/gitignore).
40 Pay attention that [`minimatch`](https://www.npmjs.org/package/minimatch) does not work in the gitignore way. To filter filenames according to .gitignore file, I recommend this module.
44 - Linux + Node: `0.8` - `7.x`
45 - Windows + Node: `0.10` - `7.x`, node < `0.10` is not tested due to the lack of support of appveyor.
47 Actually, `ignore` does not rely on any versions of node specially.
49 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](https://github.com/kaelzhang/node-ignore/blob/master/CHANGELOG.md).
51 ## Table Of Main Contents
54 - [`Pathname` Conventions](#pathname-conventions)
55 - [Guide for 2.x -> 3.x](#upgrade-2x---3x)
56 - [Guide for 3.x -> 4.x](#upgrade-3x---4x)
58 - [`glob-gitignore`](https://www.npmjs.com/package/glob-gitignore) matches files using patterns and filters them according to gitignore rules.
63 import ignore from 'ignore'
64 const ig = ignore().add(['.abc/*', '!.abc/d/'])
67 ### Filter the given paths
71 '.abc/a.js', // filtered out
72 '.abc/d/e.js' // included
75 ig.filter(paths) // ['.abc/d/e.js']
76 ig.ignores('.abc/a.js') // true
79 ### As the filter function
82 paths.filter(ig.createFilter()); // ['.abc/d/e.js']
85 ### Win32 paths will be handled
88 ig.filter(['.abc\\a.js', '.abc\\d\\e.js'])
89 // if the code above runs on windows, the result will be
93 ## Why another ignore?
95 - `ignore` is a standalone module, and is much simpler so that it could easy work with other programs, unlike [isaacs](https://npmjs.org/~isaacs)'s [fstream-ignore](https://npmjs.org/package/fstream-ignore) which must work with the modules of the fstream family.
97 - `ignore` only contains utility methods to filter paths according to the specified ignore rules, so
98 - `ignore` never try to find out ignore rules by traversing directories or fetching from git configurations.
99 - `ignore` don't cares about sub-modules of git projects.
101 - Exactly according to [gitignore man page](http://git-scm.com/docs/gitignore), fixes some known matching issues of fstream-ignore, such as:
102 - '`/*.js`' should only match '`a.js`', but not '`abc/a.js`'.
103 - '`**/foo`' should match '`foo`' anywhere.
104 - Prevent re-including a file if a parent directory of that file is excluded.
105 - Handle trailing whitespaces:
106 - `'a '`(one space) should not match `'a '`(two spaces).
107 - `'a \ '` matches `'a '`
108 - All test cases are verified with the result of `git check-ignore`.
112 ## .add(pattern: string | Ignore): this
113 ## .add(patterns: Array<string | Ignore>): this
115 - **pattern** `String | Ignore` An ignore pattern string, or the `Ignore` instance
116 - **patterns** `Array<String | Ignore>` Array of ignore patterns.
118 Adds a rule or several rules to the current manager.
122 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.
125 ignore().add('#abc').ignores('#abc') // false
126 ignore().add('\#abc').ignores('#abc') // true
129 `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:
133 .add(fs.readFileSync(filenameOfGitignore).toString())
137 `pattern` could also be an `ignore` instance, so that we could easily inherit the rules of another `Ignore` instance.
139 ## <strike>.addIgnoreFile(path)</strike>
141 REMOVED in `3.x` for now.
143 To upgrade `ignore@2.x` up to `3.x`, use
148 if (fs.existsSync(filename)) {
149 ignore().add(fs.readFileSync(filename).toString())
155 ## .filter(paths: Array<Pathname>): Array<Pathname>
158 type Pathname = string
161 Filters the given array of pathnames, and returns the filtered array.
163 - **paths** `Array.<Pathname>` The array of `pathname`s to be filtered.
165 ### `Pathname` Conventions:
167 #### 1. `Pathname` should be a `path.relative()`d pathname
169 `Pathname` should be a string that have been `path.join()`ed, or the return value of `path.relative()` to the current directory.
175 // WRONG, for it will never happen.
176 // If the gitignore rule locates at the root directory,
177 // `'/abc'` should be changed to `'abc'`.
179 // path.relative('/', '/abc') -> 'abc'
187 ig.ignores(path.join('./abc')) // path.join('./abc') -> 'abc'
190 In other words, each `Pathname` here should be a relative path to the directory of the gitignore rules.
192 Suppose the dir structure is:
205 Then the `paths` might be like this:
215 Usually, you could use [`glob`](http://npmjs.org/package/glob) with `option.mark = true` to fetch the structure of the current directory:
218 import glob from 'glob'
221 // Adds a / character to directory matches.
225 return console.error(err)
228 let filtered = ignore().add(patterns).filter(files)
229 console.log(filtered)
233 #### 2. filenames and dirnames
235 `node-ignore` does NO `fs.stat` during path matching, so for the example below:
240 // `ig` does NOT know if 'config' is a normal file, directory or something
241 ig.ignores('config') // And it returns `false`
243 ig.ignores('config/') // returns `true`
246 Specially for people who develop some library based on `node-ignore`, it is important to understand that.
248 ## .ignores(pathname: Pathname): boolean
252 Returns `Boolean` whether `pathname` should be ignored.
255 ig.ignores('.abc/a.js') // true
260 Creates a filter function which could filter an array of paths with `Array.prototype.filter`.
262 Returns `function(path)` the filter function.
264 ## `options.ignorecase` since 4.0.0
266 Similar as the `core.ignorecase` option of [git-config](https://git-scm.com/docs/git-config), `node-ignore` will be case insensitive if `options.ignorecase` is set to `true` (default value), otherwise case sensitive.
275 ig.ignores('*.PNG') // false
282 ## Upgrade 2.x -> 3.x
284 - All `options` of 2.x are unnecessary and removed, so just remove them.
285 - `ignore()` instance is no longer an [`EventEmitter`](nodejs.org/api/events.html), and all events are unnecessary and removed.
286 - `.addIgnoreFile()` is removed, see the [.addIgnoreFile](#addignorefilepath) section for details.
288 ## Upgrade 3.x -> 4.x
290 Since `4.0.0`, `ignore` will no longer support node < 6, to use `ignore` in node < 6:
293 var ignore = require('ignore/legacy')
300 - [@whitecolor](https://github.com/whitecolor) *Alex*
301 - [@SamyPesse](https://github.com/SamyPesse) *Samy Pessé*
302 - [@azproduction](https://github.com/azproduction) *Mikhail Davydov*
303 - [@TrySound](https://github.com/TrySound) *Bogdan Chadkin*
304 - [@JanMattner](https://github.com/JanMattner) *Jan Mattner*
305 - [@ntwb](https://github.com/ntwb) *Stephen Edgar*
306 - [@kasperisager](https://github.com/kasperisager) *Kasper Isager*
307 - [@sandersn](https://github.com/sandersn) *Nathan Shively-Sanders*