source: trip-planner-front/node_modules/ignore/README.md

Last change on this file was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 10.7 KB
Line 
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 2.22.1](http://git-scm.com/docs/gitignore).
39
40`ignore` is used by eslint, gitbook and [many others](https://www.npmjs.com/browse/depended/ignore).
41
42Pay **ATTENTION** that [`minimatch`](https://www.npmjs.org/package/minimatch) (which used by `fstream-ignore`) does not follow the gitignore spec.
43
44To filter filenames according to a .gitignore file, I recommend this npm package, `ignore`.
45
46To 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.
47
48### Tested on
49
50`ignore` is fully tested, and has more than **five hundreds** of unit tests.
51
52- Linux + Node: `0.8` - `7.x`
53- Windows + Node: `0.10` - `7.x`, node < `0.10` is not tested due to the lack of support of appveyor.
54
55Actually, `ignore` does not rely on any versions of node specially.
56
57Since `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).
58
59## Table Of Main Contents
60
61- [Usage](#usage)
62- [`Pathname` Conventions](#pathname-conventions)
63- See Also:
64 - [`glob-gitignore`](https://www.npmjs.com/package/glob-gitignore) matches files using patterns and filters them according to gitignore rules.
65- [Upgrade Guide](#upgrade-guide)
66
67## Install
68
69```sh
70npm i ignore
71```
72
73## Usage
74
75```js
76import ignore from 'ignore'
77const ig = ignore().add(['.abc/*', '!.abc/d/'])
78```
79
80### Filter the given paths
81
82```js
83const paths = [
84 '.abc/a.js', // filtered out
85 '.abc/d/e.js' // included
86]
87
88ig.filter(paths) // ['.abc/d/e.js']
89ig.ignores('.abc/a.js') // true
90```
91
92### As the filter function
93
94```js
95paths.filter(ig.createFilter()); // ['.abc/d/e.js']
96```
97
98### Win32 paths will be handled
99
100```js
101ig.filter(['.abc\\a.js', '.abc\\d\\e.js'])
102// if the code above runs on windows, the result will be
103// ['.abc\\d\\e.js']
104```
105
106## Why another ignore?
107
108- `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.
109
110- `ignore` only contains utility methods to filter paths according to the specified ignore rules, so
111 - `ignore` never try to find out ignore rules by traversing directories or fetching from git configurations.
112 - `ignore` don't cares about sub-modules of git projects.
113
114- Exactly according to [gitignore man page](http://git-scm.com/docs/gitignore), fixes some known matching issues of fstream-ignore, such as:
115 - '`/*.js`' should only match '`a.js`', but not '`abc/a.js`'.
116 - '`**/foo`' should match '`foo`' anywhere.
117 - Prevent re-including a file if a parent directory of that file is excluded.
118 - Handle trailing whitespaces:
119 - `'a '`(one space) should not match `'a '`(two spaces).
120 - `'a \ '` matches `'a '`
121 - All test cases are verified with the result of `git check-ignore`.
122
123# Methods
124
125## .add(pattern: string | Ignore): this
126## .add(patterns: Array<string | Ignore>): this
127
128- **pattern** `String | Ignore` An ignore pattern string, or the `Ignore` instance
129- **patterns** `Array<String | Ignore>` Array of ignore patterns.
130
131Adds a rule or several rules to the current manager.
132
133Returns `this`
134
135Notice 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.
136
137```js
138ignore().add('#abc').ignores('#abc') // false
139ignore().add('\#abc').ignores('#abc') // true
140```
141
142`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:
143
144```js
145ignore()
146.add(fs.readFileSync(filenameOfGitignore).toString())
147.filter(filenames)
148```
149
150`pattern` could also be an `ignore` instance, so that we could easily inherit the rules of another `Ignore` instance.
151
152## <strike>.addIgnoreFile(path)</strike>
153
154REMOVED in `3.x` for now.
155
156To upgrade `ignore@2.x` up to `3.x`, use
157
158```js
159import fs from 'fs'
160
161if (fs.existsSync(filename)) {
162 ignore().add(fs.readFileSync(filename).toString())
163}
164```
165
166instead.
167
168## .filter(paths: Array&lt;Pathname&gt;): Array&lt;Pathname&gt;
169
170```ts
171type Pathname = string
172```
173
174Filters the given array of pathnames, and returns the filtered array.
175
176- **paths** `Array.<Pathname>` The array of `pathname`s to be filtered.
177
178### `Pathname` Conventions:
179
180#### 1. `Pathname` should be a `path.relative()`d pathname
181
182`Pathname` should be a string that have been `path.join()`ed, or the return value of `path.relative()` to the current directory,
183
184```js
185// WRONG, an error will be thrown
186ig.ignores('./abc')
187
188// WRONG, for it will never happen, and an error will be thrown
189// If the gitignore rule locates at the root directory,
190// `'/abc'` should be changed to `'abc'`.
191// ```
192// path.relative('/', '/abc') -> 'abc'
193// ```
194ig.ignores('/abc')
195
196// WRONG, that it is an absolute path on Windows, an error will be thrown
197ig.ignores('C:\\abc')
198
199// Right
200ig.ignores('abc')
201
202// Right
203ig.ignores(path.join('./abc')) // path.join('./abc') -> 'abc'
204```
205
206In other words, each `Pathname` here should be a relative path to the directory of the gitignore rules.
207
208Suppose the dir structure is:
209
210```
211/path/to/your/repo
212 |-- a
213 | |-- a.js
214 |
215 |-- .b
216 |
217 |-- .c
218 |-- .DS_store
219```
220
221Then the `paths` might be like this:
222
223```js
224[
225 'a/a.js'
226 '.b',
227 '.c/.DS_store'
228]
229```
230
231#### 2. filenames and dirnames
232
233`node-ignore` does NO `fs.stat` during path matching, so for the example below:
234
235```js
236// First, we add a ignore pattern to ignore a directory
237ig.add('config/')
238
239// `ig` does NOT know if 'config', in the real world,
240// is a normal file, directory or something.
241
242ig.ignores('config')
243// `ig` treats `config` as a file, so it returns `false`
244
245ig.ignores('config/')
246// returns `true`
247```
248
249Specially for people who develop some library based on `node-ignore`, it is important to understand that.
250
251Usually, you could use [`glob`](http://npmjs.org/package/glob) with `option.mark = true` to fetch the structure of the current directory:
252
253```js
254import glob from 'glob'
255
256glob('**', {
257 // Adds a / character to directory matches.
258 mark: true
259}, (err, files) => {
260 if (err) {
261 return console.error(err)
262 }
263
264 let filtered = ignore().add(patterns).filter(files)
265 console.log(filtered)
266})
267```
268
269## .ignores(pathname: Pathname): boolean
270
271> new in 3.2.0
272
273Returns `Boolean` whether `pathname` should be ignored.
274
275```js
276ig.ignores('.abc/a.js') // true
277```
278
279## .createFilter()
280
281Creates a filter function which could filter an array of paths with `Array.prototype.filter`.
282
283Returns `function(path)` the filter function.
284
285## .test(pathname: Pathname) since 5.0.0
286
287Returns `TestResult`
288
289```ts
290interface TestResult {
291 ignored: boolean
292 // true if the `pathname` is finally unignored by some negative pattern
293 unignored: boolean
294}
295```
296
297- `{ignored: true, unignored: false}`: the `pathname` is ignored
298- `{ignored: false, unignored: true}`: the `pathname` is unignored
299- `{ignored: false, unignored: false}`: the `pathname` is never matched by any ignore rules.
300
301## `options.ignorecase` since 4.0.0
302
303Similar 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` (the default value), otherwise case sensitive.
304
305```js
306const ig = ignore({
307 ignorecase: false
308})
309
310ig.add('*.png')
311
312ig.ignores('*.PNG') // false
313```
314
315## static `ignore.isPathValid(pathname): boolean` since 5.0.0
316
317Check whether the `pathname` is an valid `path.relative()`d path according to the [convention](#1-pathname-should-be-a-pathrelatived-pathname).
318
319This method is **NOT** used to check if an ignore pattern is valid.
320
321```js
322ignore.isPathValid('./foo') // false
323```
324
325****
326
327# Upgrade Guide
328
329## Upgrade 4.x -> 5.x
330
331Since `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
332
333```ts
334.ignores(pathname: Pathname): boolean
335
336.filter(pathnames: Array<Pathname>): Array<Pathname>
337
338.createFilter(): (pathname: Pathname) => boolean
339
340.test(pathname: Pathname): {ignored: boolean, unignored: boolean}
341```
342
343See the convention [here](#1-pathname-should-be-a-pathrelatived-pathname) for details.
344
345If there are invalid pathnames, the conversion and filtration should be done by users.
346
347```js
348import {isPathValid} from 'ignore' // introduced in 5.0.0
349
350const paths = [
351 // invalid
352 //////////////////
353 '',
354 false,
355 '../foo',
356 '.',
357 //////////////////
358
359 // valid
360 'foo'
361]
362.filter(isValidPath)
363
364ig.filter(paths)
365```
366
367## Upgrade 3.x -> 4.x
368
369Since `4.0.0`, `ignore` will no longer support node < 6, to use `ignore` in node < 6:
370
371```js
372var ignore = require('ignore/legacy')
373```
374
375## Upgrade 2.x -> 3.x
376
377- All `options` of 2.x are unnecessary and removed, so just remove them.
378- `ignore()` instance is no longer an [`EventEmitter`](nodejs.org/api/events.html), and all events are unnecessary and removed.
379- `.addIgnoreFile()` is removed, see the [.addIgnoreFile](#addignorefilepath) section for details.
380
381****
382
383# Collaborators
384
385- [@whitecolor](https://github.com/whitecolor) *Alex*
386- [@SamyPesse](https://github.com/SamyPesse) *Samy Pessé*
387- [@azproduction](https://github.com/azproduction) *Mikhail Davydov*
388- [@TrySound](https://github.com/TrySound) *Bogdan Chadkin*
389- [@JanMattner](https://github.com/JanMattner) *Jan Mattner*
390- [@ntwb](https://github.com/ntwb) *Stephen Edgar*
391- [@kasperisager](https://github.com/kasperisager) *Kasper Isager*
392- [@sandersn](https://github.com/sandersn) *Nathan Shively-Sanders*
Note: See TracBrowser for help on using the repository browser.