.config/coc/extensions/node_modules/coc-prettier/node_modules/eslint/node_modules/ignore/README.md

   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
  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.
  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
  47 Actually, `ignore` does not rely on any versions of node specially.
  48
  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).
  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
  63 import ignore from 'ignore'
  64 const ig = ignore().add(['.abc/*', '!.abc/d/'])
  65 ```
  66
  67 ### Filter the given paths
  68
  69 ```js
  70 const paths = [
  71   '.abc/a.js',    // filtered out
  72   '.abc/d/e.js'   // included
  73 ]
  74
  75 ig.filter(paths)        // ['.abc/d/e.js']
  76 ig.ignores('.abc/a.js') // true
  77 ```
  78
  79 ### As the filter function
  80
  81 ```js
  82 paths.filter(ig.createFilter()); // ['.abc/d/e.js']
  83 ```
  84
  85 ### Win32 paths will be handled
  86
  87 ```js
  88 ig.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
 118 Adds a rule or several rules to the current manager.
 119
 120 Returns `this`
 121
 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.
 123
 124 ```js
 125 ignore().add('#abc').ignores('#abc')    // false
 126 ignore().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
 132 ignore()
 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
 141 REMOVED in `3.x` for now.
 142
 143 To upgrade `ignore@2.x` up to `3.x`, use
 144
 145 ```js
 146 import fs from 'fs'
 147
 148 if (fs.existsSync(filename)) {
 149   ignore().add(fs.readFileSync(filename).toString())
 150 }
 151 ```
 152
 153 instead.
 154
 155 ## .filter(paths: Array<Pathname>): Array<Pathname>
 156
 157 ```ts
 158 type Pathname = string
 159 ```
 160
 161 Filters 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
 173 ig.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 // ```
 181 ig.ignores('/abc')
 182
 183 // Right
 184 ig.ignores('abc')
 185
 186 // Right
 187 ig.ignores(path.join('./abc'))  // path.join('./abc') -> 'abc'
 188 ```
 189
 190 In other words, each `Pathname` here should be a relative path to the directory of the gitignore rules.
 191
 192 Suppose 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
 205 Then the `paths` might be like this:
 206
 207 ```js
 208 [
 209   'a/a.js'
 210   '.b',
 211   '.c/.DS_store'
 212 ]
 213 ```
 214
 215 Usually, you could use [`glob`](http://npmjs.org/package/glob) with `option.mark = true` to fetch the structure of the current directory:
 216
 217 ```js
 218 import glob from 'glob'
 219
 220 glob('**', {
 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
 238 ig.add('config/')
 239
 240 // `ig` does NOT know if 'config' is a normal file, directory or something
 241 ig.ignores('config')    // And it returns `false`
 242
 243 ig.ignores('config/')   // returns `true`
 244 ```
 245
 246 Specially 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
 252 Returns `Boolean` whether `pathname` should be ignored.
 253
 254 ```js
 255 ig.ignores('.abc/a.js')    // true
 256 ```
 257
 258 ## .createFilter()
 259
 260 Creates a filter function which could filter an array of paths with `Array.prototype.filter`.
 261
 262 Returns `function(path)` the filter function.
 263
 264 ## `options.ignorecase` since 4.0.0
 265
 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.
 267
 268 ```js
 269 const ig = ignore({
 270   ignorecase: false
 271 })
 272
 273 ig.add('*.png')
 274
 275 ig.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
 290 Since `4.0.0`, `ignore` will no longer support node < 6, to use `ignore` in node < 6:
 291
 292 ```js
 293 var 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*