diff options
Diffstat (limited to 'assets/node_modules/ignore/README.md')
| -rw-r--r-- | assets/node_modules/ignore/README.md | 386 |
1 files changed, 0 insertions, 386 deletions
diff --git a/assets/node_modules/ignore/README.md b/assets/node_modules/ignore/README.md deleted file mode 100644 index c52b325..0000000 --- a/assets/node_modules/ignore/README.md +++ /dev/null @@ -1,386 +0,0 @@ -<table><thead> - <tr> - <th>Linux</th> - <th>OS X</th> - <th>Windows</th> - <th>Coverage</th> - <th>Downloads</th> - </tr> -</thead><tbody><tr> - <td colspan="2" align="center"> - <a href="https://travis-ci.org/kaelzhang/node-ignore"> - <img - src="https://travis-ci.org/kaelzhang/node-ignore.svg?branch=master" - alt="Build Status" /></a> - </td> - <td align="center"> - <a href="https://ci.appveyor.com/project/kaelzhang/node-ignore"> - <img - src="https://ci.appveyor.com/api/projects/status/github/kaelzhang/node-ignore?branch=master&svg=true" - alt="Windows Build Status" /></a> - </td> - <td align="center"> - <a href="https://codecov.io/gh/kaelzhang/node-ignore"> - <img - src="https://codecov.io/gh/kaelzhang/node-ignore/branch/master/graph/badge.svg" - alt="Coverage Status" /></a> - </td> - <td align="center"> - <a href="https://www.npmjs.org/package/ignore"> - <img - src="http://img.shields.io/npm/dm/ignore.svg" - alt="npm module downloads per month" /></a> - </td> -</tr></tbody></table> - -# ignore - -`ignore` is a manager, filter and parser which implemented in pure JavaScript according to the .gitignore [spec](http://git-scm.com/docs/gitignore). - -`ignore` is used by eslint, gitbook and [many others](https://www.npmjs.com/browse/depended/ignore). - -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. - -### Tested on - -`ignore` is fully tested, and has more than **five hundreds** of unit tests. - -- Linux + Node: `0.8` - `7.x` -- Windows + Node: `0.10` - `7.x`, node < `0.10` is not tested due to the lack of support of appveyor. - -Actually, `ignore` does not rely on any versions of node specially. - -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). - -## Table Of Main Contents - -- [Usage](#usage) -- [`Pathname` Conventions](#pathname-conventions) -- See Also: - - [`glob-gitignore`](https://www.npmjs.com/package/glob-gitignore) matches files using patterns and filters them according to gitignore rules. -- [Upgrade Guide](#upgrade-guide) - -## Install - -```sh -npm i ignore -``` - -## Usage - -```js -import ignore from 'ignore' -const ig = ignore().add(['.abc/*', '!.abc/d/']) -``` - -### Filter the given paths - -```js -const paths = [ - '.abc/a.js', // filtered out - '.abc/d/e.js' // included -] - -ig.filter(paths) // ['.abc/d/e.js'] -ig.ignores('.abc/a.js') // true -``` - -### As the filter function - -```js -paths.filter(ig.createFilter()); // ['.abc/d/e.js'] -``` - -### Win32 paths will be handled - -```js -ig.filter(['.abc\\a.js', '.abc\\d\\e.js']) -// if the code above runs on windows, the result will be -// ['.abc\\d\\e.js'] -``` - -## Why another ignore? - -- `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. - -- `ignore` only contains utility methods to filter paths according to the specified ignore rules, so - - `ignore` never try to find out ignore rules by traversing directories or fetching from git configurations. - - `ignore` don't cares about sub-modules of git projects. - -- Exactly according to [gitignore man page](http://git-scm.com/docs/gitignore), fixes some known matching issues of fstream-ignore, such as: - - '`/*.js`' should only match '`a.js`', but not '`abc/a.js`'. - - '`**/foo`' should match '`foo`' anywhere. - - Prevent re-including a file if a parent directory of that file is excluded. - - Handle trailing whitespaces: - - `'a '`(one space) should not match `'a '`(two spaces). - - `'a \ '` matches `'a '` - - All test cases are verified with the result of `git check-ignore`. - -# Methods - -## .add(pattern: string | Ignore): this -## .add(patterns: Array<string | Ignore>): this - -- **pattern** `String | Ignore` An ignore pattern string, or the `Ignore` instance -- **patterns** `Array<String | Ignore>` Array of ignore patterns. - -Adds a rule or several rules to the current manager. - -Returns `this` - -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. - -```js -ignore().add('#abc').ignores('#abc') // false -ignore().add('\#abc').ignores('#abc') // true -``` - -`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: - -```js -ignore() -.add(fs.readFileSync(filenameOfGitignore).toString()) -.filter(filenames) -``` - -`pattern` could also be an `ignore` instance, so that we could easily inherit the rules of another `Ignore` instance. - -## <strike>.addIgnoreFile(path)</strike> - -REMOVED in `3.x` for now. - -To upgrade `ignore@2.x` up to `3.x`, use - -```js -import fs from 'fs' - -if (fs.existsSync(filename)) { - ignore().add(fs.readFileSync(filename).toString()) -} -``` - -instead. - -## .filter(paths: Array<Pathname>): Array<Pathname> - -```ts -type Pathname = string -``` - -Filters the given array of pathnames, and returns the filtered array. - -- **paths** `Array.<Pathname>` The array of `pathname`s to be filtered. - -### `Pathname` Conventions: - -#### 1. `Pathname` should be a `path.relative()`d pathname - -`Pathname` should be a string that have been `path.join()`ed, or the return value of `path.relative()` to the current directory, - -```js -// WRONG, an error will be thrown -ig.ignores('./abc') - -// WRONG, for it will never happen, and an error will be thrown -// If the gitignore rule locates at the root directory, -// `'/abc'` should be changed to `'abc'`. -// ``` -// path.relative('/', '/abc') -> 'abc' -// ``` -ig.ignores('/abc') - -// WRONG, that it is an absolute path on Windows, an error will be thrown -ig.ignores('C:\\abc') - -// Right -ig.ignores('abc') - -// Right -ig.ignores(path.join('./abc')) // path.join('./abc') -> 'abc' -``` - -In other words, each `Pathname` here should be a relative path to the directory of the gitignore rules. - -Suppose the dir structure is: - -``` -/path/to/your/repo - |-- a - | |-- a.js - | - |-- .b - | - |-- .c - |-- .DS_store -``` - -Then the `paths` might be like this: - -```js -[ - 'a/a.js' - '.b', - '.c/.DS_store' -] -``` - -#### 2. filenames and dirnames - -`node-ignore` does NO `fs.stat` during path matching, so for the example below: - -```js -// First, we add a ignore pattern to ignore a directory -ig.add('config/') - -// `ig` does NOT know if 'config', in the real world, -// is a normal file, directory or something. - -ig.ignores('config') -// `ig` treats `config` as a file, so it returns `false` - -ig.ignores('config/') -// returns `true` -``` - -Specially for people who develop some library based on `node-ignore`, it is important to understand that. - -Usually, you could use [`glob`](http://npmjs.org/package/glob) with `option.mark = true` to fetch the structure of the current directory: - -```js -import glob from 'glob' - -glob('**', { - // Adds a / character to directory matches. - mark: true -}, (err, files) => { - if (err) { - return console.error(err) - } - - let filtered = ignore().add(patterns).filter(files) - console.log(filtered) -}) -``` - -## .ignores(pathname: Pathname): boolean - -> new in 3.2.0 - -Returns `Boolean` whether `pathname` should be ignored. - -```js -ig.ignores('.abc/a.js') // true -``` - -## .createFilter() - -Creates a filter function which could filter an array of paths with `Array.prototype.filter`. - -Returns `function(path)` the filter function. - -## .test(pathname: Pathname) since 5.0.0 - -Returns `TestResult` - -```ts -interface TestResult { - ignored: boolean - // true if the `pathname` is finally unignored by some negative pattern - unignored: boolean -} -``` - -- `{ignored: true, unignored: false}`: the `pathname` is ignored -- `{ignored: false, unignored: true}`: the `pathname` is unignored -- `{ignored: false, unignored: false}`: the `pathname` is never matched by any ignore rules. - -## `options.ignorecase` since 4.0.0 - -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` (the default value), otherwise case sensitive. - -```js -const ig = ignore({ - ignorecase: false -}) - -ig.add('*.png') - -ig.ignores('*.PNG') // false -``` - -## static `ignore.isPathValid(pathname): boolean` since 5.0.0 - -Check whether the `pathname` is valid according to the [convention](#1-pathname-should-be-a-pathrelatived-pathname). - -```js -ignore.isPathValid('./foo') // false -``` - -**** - -# Upgrade Guide - -## Upgrade 4.x -> 5.x - -Since `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 - -```ts -.ignores(pathname: Pathname): boolean - -.filter(pathnames: Array<Pathname>): Array<Pathname> - -.createFilter(): (pathname: Pathname) => boolean - -.test(pathname: Pathname): {ignored: boolean, unignored: boolean} -``` - -See the convention [here](#1-pathname-should-be-a-pathrelatived-pathname) for details. - -If there are invalid pathnames, the conversion and filtration should be done by users. - -```js -import {isPathValid} from 'ignore' // introduced in 5.0.0 - -const paths = [ - // invalid - ////////////////// - '', - false, - '../foo', - '.', - ////////////////// - - // valid - 'foo' -] -.filter(isValidPath) - -ig.filter(paths) -``` - -## Upgrade 3.x -> 4.x - -Since `4.0.0`, `ignore` will no longer support node < 6, to use `ignore` in node < 6: - -```js -var ignore = require('ignore/legacy') -``` - -## Upgrade 2.x -> 3.x - -- All `options` of 2.x are unnecessary and removed, so just remove them. -- `ignore()` instance is no longer an [`EventEmitter`](nodejs.org/api/events.html), and all events are unnecessary and removed. -- `.addIgnoreFile()` is removed, see the [.addIgnoreFile](#addignorefilepath) section for details. - -**** - -# Collaborators - -- [@whitecolor](https://github.com/whitecolor) *Alex* -- [@SamyPesse](https://github.com/SamyPesse) *Samy Pessé* -- [@azproduction](https://github.com/azproduction) *Mikhail Davydov* -- [@TrySound](https://github.com/TrySound) *Bogdan Chadkin* -- [@JanMattner](https://github.com/JanMattner) *Jan Mattner* -- [@ntwb](https://github.com/ntwb) *Stephen Edgar* -- [@kasperisager](https://github.com/kasperisager) *Kasper Isager* -- [@sandersn](https://github.com/sandersn) *Nathan Shively-Sanders* |