Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/kaelzhang/node-ignore

🔍 node-ignore is the manager and filter for .gitignore rules, the one used by eslint, prettier and many others.
https://github.com/kaelzhang/node-ignore
gitignore ignore-files ignore-patterns ignore-rules javascript nodejs
Last synced: 5 days ago
JSON representation
🔍 node-ignore is the manager and filter for .gitignore rules, the one used by eslint, prettier and many others.
Host: GitHub
URL: https://github.com/kaelzhang/node-ignore
Owner: kaelzhang
License: other
Created: 2013-09-01T10:52:11.000Z (over 11 years ago)
Default Branch: master
Last Pushed: 2024-11-19T15:41:44.000Z (about 1 month ago)
Last Synced: 2024-12-13T21:51:38.492Z (8 days ago)
Topics: gitignore, ignore-files, ignore-patterns, ignore-rules, javascript, nodejs
Language: JavaScript
Homepage:
Size: 280 KB
Stars: 446
Watchers: 9
Forks: 45
Open Issues: 8
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE-MIT
Awesome Lists containing this project

README

        
  

    Linux

    OS X

    Windows

    Coverage

    Downloads

  

  

    

    

  

  

    

    

  

  

    

    

  

  

    

    

  

# ignore

`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).

`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) (which used by `fstream-ignore`) does not follow the gitignore spec.

To filter filenames according to a .gitignore file, I recommend this npm package, `ignore`.

To 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.

### 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): this

- **pattern** `String | Ignore` An ignore pattern string, or the `Ignore` instance

- **patterns** `Array` 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.

## .addIgnoreFile(path)

REMOVED in `3.x` for now.

To upgrade `[email protected]` 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.` 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.

## static `isPathValid(pathname): boolean` since 5.0.0

Check whether the `pathname` is an valid `path.relative()`d path according to the [convention](#1-pathname-should-be-a-pathrelatived-pathname).

This method is **NOT** used to check if an ignore pattern is valid.

```js

import {isPathValid} from 'ignore'

isPathValid('./foo')  // false

```

## ignore(options)

### `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

```

### `options.ignoreCase?: boolean` since 5.2.0

Which is alternative to `options.ignoreCase`

### `options.allowRelativePaths?: boolean` since 5.2.0

This option brings backward compatibility with projects which based on `[email protected]`. If `options.allowRelativePaths` is `true`, `ignore` will not check whether the given path to be tested is [`path.relative()`d](#pathname-conventions).

However, passing a relative path, such as `'./foo'` or `'../foo'`, to test if it is ignored or not is not a good practise, which might lead to unexpected behavior

```js

ignore({

  allowRelativePaths: true

}).ignores('../foo/bar.js') // And it will not throw

```

****

# Upgrade Guide

## Upgrade 5.x -> 6.x

To bring better compatibility for TypeScript with `moduleResolution:Node16`, `ignore.isPathValid` has been removed in TypeScript definitions since `6.x`

```js

// < 6, or works with commonjs

ignore.isPathValid('./foo')  // false

// >= 6.x

import {isPathValid} from 'ignore'

isPathValid('./foo')         // false

```

## Upgrade 4.x -> 5.x

Since `5.0.0`, if an invalid `Pathname` passed into `ig.ignores()`, an error will be thrown, unless `options.allowRelative = true` is passed to the `Ignore` factory.

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): Array

.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(isPathValid)

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*