ignore

What is ignore?

The ignore npm package is a utility for filtering files and directories according to the particular rules specified in .gitignore files. It can be used to create ignore patterns similar to how git handles .gitignore files, allowing developers to programmatically determine which files should be ignored based on these patterns.

What are ignore's main functionalities?

Add ignore rules

This feature allows you to add ignore rules, which can be a single string or an array of strings representing the patterns to ignore. The example demonstrates adding rules to ignore the .git directory and any files ending with .test.js.

const ignore = require('ignore');
const ig = ignore().add(['.git', '*.test.js']);
console.log(ig.ignores('example.test.js')); // true

Filter file paths

This feature provides a way to filter an array of file paths, removing any that match the ignore patterns. The code sample filters out 'example.test.js' because it matches the '*.test.js' pattern.

const ignore = require('ignore');
const ig = ignore().add('*.test.js');
const files = ['test.js', 'example.test.js', 'README.md'];
const filtered = files.filter(ig.createFilter());
console.log(filtered); // ['test.js', 'README.md']

Check if a file is ignored

This feature checks if a particular file would be ignored based on the current ignore rules. The code sample checks if 'example.test.js' is ignored (true) and if 'README.md' is ignored (false).

const ignore = require('ignore');
const ig = ignore().add('*.test.js');
console.log(ig.ignores('example.test.js')); // true
console.log(ig.ignores('README.md')); // false

Other packages similar to ignore

globby

Globby is a package that provides methods for matching files using glob patterns. It is built on top of the 'glob' package and supports multiple patterns. It is similar to ignore in that it can filter out files, but it uses glob patterns instead of .gitignore-style patterns.

minimatch

Minimatch is a minimal matching utility that implements the same wildcard rules as used by gitignore. It is similar to ignore in that it can be used to test if file paths match specified patterns, but it does not directly handle .gitignore files.

anymatch

Anymatch is a package that allows you to match strings against a list of patterns, which can be strings, regexes, or functions. It is similar to ignore in the sense that it can be used to determine if a string should be ignored or not, but it is more flexible in terms of the types of patterns it accepts.

README

ignore

ignore is a manager and filter for .gitignore rules.

Installation

npm install ignore --save

Usage

var ignore = require('ignore');
var ig = ignore({
    ignore: [
        '.abc/*' // or use the `.add()` method
    ]

}).add('!.abc/d/');

var paths = [
    '.abc/a.js',    // filtered out
    '.abc/d/e.js'   // included
];

ig.filter(paths); // ['.abc/d/e.js']
paths.filter(ig.createFilter()); // ['.abc/d/e.js']

Why another ignore?

1. ignore is a standalone module, and is much simpler so that it could easily work with other programs, unlike isaacs's fstream-ignore which must work with the modules of the fstream family.

2. ignore only contains utility methods to filter paths according to the specified ignore rules.

3. Exactly according to gitignore man page, fixes some known matching issues of fstream-ignore, such as:

   • '/*.js' should match 'a.js', but not 'abc/a.js'.
   • '**/foo' should match 'foo' anywhere.

Methods

.add(rule)

Adds a rule or several rules to the current manager.

Returns this

Rule String|Array.<String>

The ignore rule or a array of rules.

.filter(paths)

Filters the given array of pathnames, and returns the filtered array.

paths Array

The array of paths to be filtered

.createFilter()

Creates a filter function which could be used with Array.prototype.filter.

Returns function(path)

The filter function.

Constructor: ignore.Ignore

new ignore.Ignore(options);
ignore(options);

options.noCase boolean=true

By default, all ignore rules will be treated as case-insensitive ones as well as the git does.

options.twoGlobstars boolean=false

By defailt, ignoreRules will omit every pattern that includes '**' (two consecutive asterisks) which is not compatible cross operating systems, because the behavior of file .gitignore depends on the implementation of command fnmatch in shell.

By the way, Mac OS doesn't support '**'.

options.ignore Array.<String>

The ignore rules to be added.

You can also use .add() method to do this.