1<table><thead> 2 <tr> 3 <th>Linux</th> 4 <th>OS X</th> 5 <th>Windows</th> 6 <th>Coverage</th> 7 <th>Downloads</th> 8 </tr> 9</thead><tbody><tr> 10 <td colspan="2" align="center"> 11 <a href="https://travis-ci.org/kaelzhang/node-ignore"> 12 <img 13 src="https://travis-ci.org/kaelzhang/node-ignore.svg?branch=master" 14 alt="Build Status" /></a> 15 </td> 16 <td align="center"> 17 <a href="https://ci.appveyor.com/project/kaelzhang/node-ignore"> 18 <img 19 src="https://ci.appveyor.com/api/projects/status/github/kaelzhang/node-ignore?branch=master&svg=true" 20 alt="Windows Build Status" /></a> 21 </td> 22 <td align="center"> 23 <a href="https://codecov.io/gh/kaelzhang/node-ignore"> 24 <img 25 src="https://codecov.io/gh/kaelzhang/node-ignore/branch/master/graph/badge.svg" 26 alt="Coverage Status" /></a> 27 </td> 28 <td align="center"> 29 <a href="https://www.npmjs.org/package/ignore"> 30 <img 31 src="http://img.shields.io/npm/dm/ignore.svg" 32 alt="npm module downloads per month" /></a> 33 </td> 34</tr></tbody></table> 35 36# ignore 37 38`ignore` is a manager, filter and parser which implemented in pure JavaScript according to the .gitignore [spec](http://git-scm.com/docs/gitignore). 39 40Pay 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. 41 42##### Tested on 43 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. 46 47Actually, `ignore` does not rely on any versions of node specially. 48 49Since `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). 50 51## Table Of Main Contents 52 53- [Usage](#usage) 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) 57- See Also: 58 - [`glob-gitignore`](https://www.npmjs.com/package/glob-gitignore) matches files using patterns and filters them according to gitignore rules. 59 60## Usage 61 62```js 63import ignore from 'ignore' 64const ig = ignore().add(['.abc/*', '!.abc/d/']) 65``` 66 67### Filter the given paths 68 69```js 70const paths = [ 71 '.abc/a.js', // filtered out 72 '.abc/d/e.js' // included 73] 74 75ig.filter(paths) // ['.abc/d/e.js'] 76ig.ignores('.abc/a.js') // true 77``` 78 79### As the filter function 80 81```js 82paths.filter(ig.createFilter()); // ['.abc/d/e.js'] 83``` 84 85### Win32 paths will be handled 86 87```js 88ig.filter(['.abc\\a.js', '.abc\\d\\e.js']) 89// if the code above runs on windows, the result will be 90// ['.abc\\d\\e.js'] 91``` 92 93## Why another ignore? 94 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. 96 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. 100 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`. 109 110# Methods 111 112## .add(pattern: string | Ignore): this 113## .add(patterns: Array<string | Ignore>): this 114 115- **pattern** `String | Ignore` An ignore pattern string, or the `Ignore` instance 116- **patterns** `Array<String | Ignore>` Array of ignore patterns. 117 118Adds a rule or several rules to the current manager. 119 120Returns `this` 121 122Notice 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. 123 124```js 125ignore().add('#abc').ignores('#abc') // false 126ignore().add('\#abc').ignores('#abc') // true 127``` 128 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: 130 131```js 132ignore() 133.add(fs.readFileSync(filenameOfGitignore).toString()) 134.filter(filenames) 135``` 136 137`pattern` could also be an `ignore` instance, so that we could easily inherit the rules of another `Ignore` instance. 138 139## <strike>.addIgnoreFile(path)</strike> 140 141REMOVED in `3.x` for now. 142 143To upgrade `ignore@2.x` up to `3.x`, use 144 145```js 146import fs from 'fs' 147 148if (fs.existsSync(filename)) { 149 ignore().add(fs.readFileSync(filename).toString()) 150} 151``` 152 153instead. 154 155## .filter(paths: Array<Pathname>): Array<Pathname> 156 157```ts 158type Pathname = string 159``` 160 161Filters the given array of pathnames, and returns the filtered array. 162 163- **paths** `Array.<Pathname>` The array of `pathname`s to be filtered. 164 165### `Pathname` Conventions: 166 167#### 1. `Pathname` should be a `path.relative()`d pathname 168 169`Pathname` should be a string that have been `path.join()`ed, or the return value of `path.relative()` to the current directory. 170 171```js 172// WRONG 173ig.ignores('./abc') 174 175// WRONG, for it will never happen. 176// If the gitignore rule locates at the root directory, 177// `'/abc'` should be changed to `'abc'`. 178// ``` 179// path.relative('/', '/abc') -> 'abc' 180// ``` 181ig.ignores('/abc') 182 183// Right 184ig.ignores('abc') 185 186// Right 187ig.ignores(path.join('./abc')) // path.join('./abc') -> 'abc' 188``` 189 190In other words, each `Pathname` here should be a relative path to the directory of the gitignore rules. 191 192Suppose the dir structure is: 193 194``` 195/path/to/your/repo 196 |-- a 197 | |-- a.js 198 | 199 |-- .b 200 | 201 |-- .c 202 |-- .DS_store 203``` 204 205Then the `paths` might be like this: 206 207```js 208[ 209 'a/a.js' 210 '.b', 211 '.c/.DS_store' 212] 213``` 214 215Usually, you could use [`glob`](http://npmjs.org/package/glob) with `option.mark = true` to fetch the structure of the current directory: 216 217```js 218import glob from 'glob' 219 220glob('**', { 221 // Adds a / character to directory matches. 222 mark: true 223}, (err, files) => { 224 if (err) { 225 return console.error(err) 226 } 227 228 let filtered = ignore().add(patterns).filter(files) 229 console.log(filtered) 230}) 231``` 232 233#### 2. filenames and dirnames 234 235`node-ignore` does NO `fs.stat` during path matching, so for the example below: 236 237```js 238ig.add('config/') 239 240// `ig` does NOT know if 'config' is a normal file, directory or something 241ig.ignores('config') // And it returns `false` 242 243ig.ignores('config/') // returns `true` 244``` 245 246Specially for people who develop some library based on `node-ignore`, it is important to understand that. 247 248## .ignores(pathname: Pathname): boolean 249 250> new in 3.2.0 251 252Returns `Boolean` whether `pathname` should be ignored. 253 254```js 255ig.ignores('.abc/a.js') // true 256``` 257 258## .createFilter() 259 260Creates a filter function which could filter an array of paths with `Array.prototype.filter`. 261 262Returns `function(path)` the filter function. 263 264## `options.ignorecase` since 4.0.0 265 266Similar 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. 267 268```js 269const ig = ignore({ 270 ignorecase: false 271}) 272 273ig.add('*.png') 274 275ig.ignores('*.PNG') // false 276``` 277 278**** 279 280# Upgrade Guide 281 282## Upgrade 2.x -> 3.x 283 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. 287 288## Upgrade 3.x -> 4.x 289 290Since `4.0.0`, `ignore` will no longer support node < 6, to use `ignore` in node < 6: 291 292```js 293var ignore = require('ignore/legacy') 294``` 295 296**** 297 298# Collaborators 299 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* 308
