.config/coc/extensions/node_modules/coc-prettier/node_modules/prettier-tslint/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 ## Table Of Main Contents
  50
  51 - [Usage](#usage)
  52 - [Guide for 2.x -> 3.x](#upgrade-2x---3x)
  53 - [Contributing](#contributing)
  54 - Related Packages
  55   - [`glob-gitignore`](https://www.npmjs.com/package/glob-gitignore) matches files using patterns and filters them according to gitignore rules.
  56
  57 ## Usage
  58
  59 ```js
  60 const ignore = require('ignore')
  61 const ig = ignore().add(['.abc/*', '!.abc/d/'])
  62 ```
  63
  64 ### Filter the given paths
  65
  66 ```js
  67 const paths = [
  68   '.abc/a.js',    // filtered out
  69   '.abc/d/e.js'   // included
  70 ]
  71
  72 ig.filter(paths)        // ['.abc/d/e.js']
  73 ig.ignores('.abc/a.js') // true
  74 ```
  75
  76 ### As the filter function
  77
  78 ```js
  79 paths.filter(ig.createFilter()); // ['.abc/d/e.js']
  80 ```
  81
  82 ### Win32 paths will be handled
  83
  84 ```js
  85 ig.filter(['.abc\\a.js', '.abc\\d\\e.js'])
  86 // if the code above runs on windows, the result will be
  87 // ['.abc\\d\\e.js']
  88 ```
  89
  90 ## Why another ignore?
  91
  92 - `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.
  93
  94 - `ignore` only contains utility methods to filter paths according to the specified ignore rules, so
  95   - `ignore` never try to find out ignore rules by traversing directories or fetching from git configurations.
  96   - `ignore` don't cares about sub-modules of git projects.
  97
  98 - Exactly according to [gitignore man page](http://git-scm.com/docs/gitignore), fixes some known matching issues of fstream-ignore, such as:
  99   - '`/*.js`' should only match '`a.js`', but not '`abc/a.js`'.
 100   - '`**/foo`' should match '`foo`' anywhere.
 101   - Prevent re-including a file if a parent directory of that file is excluded.
 102   - Handle trailing whitespaces:
 103     - `'a '`(one space) should not match `'a  '`(two spaces).
 104     - `'a \ '` matches `'a  '`
 105   - All test cases are verified with the result of `git check-ignore`.
 106
 107 ## Methods
 108
 109 ### .add(pattern)
 110 ### .add(patterns)
 111
 112 - **pattern** `String|Ignore` An ignore pattern string, or the `Ignore` instance
 113 - **patterns** `Array.<pattern>` Array of ignore patterns.
 114
 115 Adds a rule or several rules to the current manager.
 116
 117 Returns `this`
 118
 119 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.
 120
 121 ```js
 122 ignore().add('#abc').ignores('#abc')    // false
 123 ignore().add('\#abc').ignores('#abc')   // true
 124 ```
 125
 126 `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:
 127
 128 ```js
 129 ignore()
 130 .add(fs.readFileSync(filenameOfGitignore).toString())
 131 .filter(filenames)
 132 ```
 133
 134 `pattern` could also be an `ignore` instance, so that we could easily inherit the rules of another `Ignore` instance.
 135
 136 ### <strike>.addIgnoreFile(path)</strike>
 137
 138 REMOVED in `3.x` for now.
 139
 140 To upgrade `ignore@2.x` up to `3.x`, use
 141
 142 ```js
 143 const fs = require('fs')
 144
 145 if (fs.existsSync(filename)) {
 146   ignore().add(fs.readFileSync(filename).toString())
 147 }
 148 ```
 149
 150 instead.
 151
 152
 153 ### .ignores(pathname)
 154
 155 > new in 3.2.0
 156
 157 Returns `Boolean` whether `pathname` should be ignored.
 158
 159 ```js
 160 ig.ignores('.abc/a.js')    // true
 161 ```
 162
 163 ### .filter(paths)
 164
 165 Filters the given array of pathnames, and returns the filtered array.
 166
 167 - **paths** `Array.<path>` The array of `pathname`s to be filtered.
 168
 169 **NOTICE** that:
 170
 171 - `pathname` should be a string that have been `path.join()`ed, or the return value of `path.relative()` to the current directory.
 172
 173 ```js
 174 // WRONG
 175 ig.ignores('./abc')
 176
 177 // WRONG, for it will never happen.
 178 // If the gitignore rule locates at the root directory,
 179 // `'/abc'` should be changed to `'abc'`.
 180 // ```
 181 // path.relative('/', '/abc')  -> 'abc'
 182 // ```
 183 ig.ignores('/abc')
 184
 185 // Right
 186 ig.ignores('abc')
 187
 188 // Right
 189 ig.ignores(path.join('./abc'))  // path.join('./abc') -> 'abc'
 190 ```
 191
 192 - In other words, each `pathname` here should be a relative path to the directory of the git ignore rules.
 193
 194 Suppose the dir structure is:
 195
 196 ```
 197 /path/to/your/repo
 198     |-- a
 199     |   |-- a.js
 200     |
 201     |-- .b
 202     |
 203     |-- .c
 204          |-- .DS_store
 205 ```
 206
 207 Then the `paths` might be like this:
 208
 209 ```js
 210 [
 211   'a/a.js'
 212   '.b',
 213   '.c/.DS_store'
 214 ]
 215 ```
 216
 217 Usually, you could use [`glob`](http://npmjs.org/package/glob) with `option.mark = true` to fetch the structure of the current directory:
 218
 219 ```js
 220 const glob = require('glob')
 221
 222 glob('**', {
 223   // Adds a / character to directory matches.
 224   mark: true
 225 }, (err, files) => {
 226   if (err) {
 227     return console.error(err)
 228   }
 229
 230   let filtered = ignore().add(patterns).filter(files)
 231   console.log(filtered)
 232 })
 233 ```
 234
 235 ### .createFilter()
 236
 237 Creates a filter function which could filter an array of paths with `Array.prototype.filter`.
 238
 239 Returns `function(path)` the filter function.
 240
 241 ****
 242
 243 ## Upgrade 2.x -> 3.x
 244
 245 - All `options` of 2.x are unnecessary and removed, so just remove them.
 246 - `ignore()` instance is no longer an [`EventEmitter`](nodejs.org/api/events.html), and all events are unnecessary and removed.
 247 - `.addIgnoreFile()` is removed, see the [.addIgnoreFile](#addignorefilepath) section for details.
 248
 249 ****
 250
 251 ## Contributing
 252
 253 The code of `node-ignore` is based on es6 and babel, but babel and its preset is not included in the `dependencies` field of package.json, so that the installation process of test cases will not fail in older versions of node.
 254
 255 So use `bash install.sh` to install dependencies and `bash test.sh` to run test cases in your local machine.
 256
 257 #### Collaborators
 258
 259 - [SamyPesse](https://github.com/SamyPesse) *Samy Pessé*
 260 - [azproduction](https://github.com/azproduction) *Mikhail Davydov*
 261 - [TrySound](https://github.com/TrySound) *Bogdan Chadkin*
 262 - [JanMattner](https://github.com/JanMattner) *Jan Mattner*