Gathering detailed insights and metrics for ignore
🔍 node-ignore is the manager and filter for .gitignore rules, the one used by eslint, prettier and many others.
Installations
npm install ignoreDeveloper Guide
BETA
Typescript
Yes
Module System
N/A
Min. Node Version
>= 4
Node Version
22.8.0
NPM Version
10.8.2
Score
99.6
Supply Chain
99.6
Quality
89.4
Maintenance
100
Vulnerability
100
License
Releases
14
Contributors
20
Languages
2
JavaScript
TypeScript
JavaScript (95.21%)
TypeScript (4.79%)
Developer
kaelzhang
Download Statistics
Total Downloads
12,359,433,233
Last Day
12,041,632
Last Week
54,596,507
Last Month
244,628,972
Last Year
3,034,466,848
GitHub Statistics
458 Stars
340 Commits
46 Forks
10 Watching
3 Branches
20 Contributors
Bundle Size
4.34 kB
Minified
1.97 kB
Minified + Gzipped
Maintainers
1
Package Meta Information
Latest Version
7.0.3
Package Id
ignore@7.0.3
Unpacked Size
61.67 kB
Size
16.80 kB
File Count
6
NPM Version
10.8.2
Node Version
22.8.0
Publised On
14 Jan 2025
Total Downloads
Cumulative downloads
Total Downloads
12,359,433,233
Last day
-3.2%
12,041,632
Compared to previous day
Last week
-14.7%
54,596,507
Compared to previous week
Last month
5.4%
244,628,972
Compared to previous month
Last year
11.4%
3,034,466,848
Compared to previous year
Daily Downloads
Weekly Downloads
Monthly Downloads
Yearly Downloads
Versions
| Linux / MacOS / Windows | Coverage | Downloads |
|---|---|---|
 |  |  |
ignore
ignore is a manager, filter and parser which implemented in pure JavaScript according to the .gitignore spec 2.22.1.
ignore is used by eslint, gitbook and many others.
Pay ATTENTION that 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.10is 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.
Table Of Main Contents
- Usage
PathnameConventions- See Also:
glob-gitignorematches files using patterns and filters them according to gitignore rules.
- Upgrade Guide
Install
1npm i ignore
Usage
1import ignore from 'ignore' 2const ig = ignore().add(['.abc/*', '!.abc/d/'])
Filter the given paths
1const paths = [ 2 '.abc/a.js', // filtered out 3 '.abc/d/e.js' // included 4] 5 6ig.filter(paths) // ['.abc/d/e.js'] 7ig.ignores('.abc/a.js') // true
As the filter function
1paths.filter(ig.createFilter()); // ['.abc/d/e.js']
Win32 paths will be handled
1ig.filter(['.abc\\a.js', '.abc\\d\\e.js']) 2// if the code above runs on windows, the result will be 3// ['.abc\\d\\e.js']
Why another ignore?
-
ignoreis a standalone module, and is much simpler so that it could easy work with other programs, unlike isaacs's fstream-ignore which must work with the modules of the fstream family. -
ignoreonly contains utility methods to filter paths according to the specified ignore rules, soignorenever try to find out ignore rules by traversing directories or fetching from git configurations.ignoredon't cares about sub-modules of git projects.
-
Exactly according to gitignore man page, 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
.add({pattern: string, mark?: string}): this since 7.0.0
- pattern
string | IgnoreAn ignore pattern string, or theIgnoreinstance - patterns
Array<string | Ignore>Array of ignore patterns. - mark?
stringPattern mark, which is used to associate the pattern with a certain marker, such as the line no of the.gitignorefile. Actually it could be an arbitrary string and is optional.
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.
1ignore().add('#abc').ignores('#abc') // false 2ignore().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:
1ignore() 2.add(fs.readFileSync(filenameOfGitignore).toString()) 3.filter(filenames)
pattern could also be an ignore instance, so that we could easily inherit the rules of another Ignore instance.
.ignores(pathname: Pathname): boolean
new in 3.2.0
Returns Boolean whether pathname should be ignored.
1ig.ignores('.abc/a.js') // true
Please PAY ATTENTION that .ignores() is NOT equivalent to git check-ignore although in most cases they return equivalent results.
However, for the purposes of imitating the behavior of git check-ignore, please use .checkIgnore() instead.
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,
1// WRONG, an error will be thrown 2ig.ignores('./abc') 3 4// WRONG, for it will never happen, and an error will be thrown 5// If the gitignore rule locates at the root directory, 6// `'/abc'` should be changed to `'abc'`. 7// ``` 8// path.relative('/', '/abc') -> 'abc' 9// ``` 10ig.ignores('/abc') 11 12// WRONG, that it is an absolute path on Windows, an error will be thrown 13ig.ignores('C:\\abc') 14 15// Right 16ig.ignores('abc') 17 18// Right 19ig.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:
1[ 2 'a/a.js' 3 '.b', 4 '.c/.DS_store' 5]
2. filenames and dirnames
node-ignore does NO fs.stat during path matching, so node-ignore treats
fooas a filefoo/as a directory
For the example below:
1// First, we add a ignore pattern to ignore a directory 2ig.add('config/') 3 4// `ig` does NOT know if 'config', in the real world, 5// is a normal file, directory or something. 6 7ig.ignores('config') 8// `ig` treats `config` as a file, so it returns `false` 9 10ig.ignores('config/') 11// returns `true`
Specially for people who develop some library based on node-ignore, it is important to understand that.
Usually, you could use glob with option.mark = true to fetch the structure of the current directory:
1import glob from 'glob' 2 3glob('**', { 4 // Adds a / character to directory matches. 5 mark: true 6}, (err, files) => { 7 if (err) { 8 return console.error(err) 9 } 10 11 let filtered = ignore().add(patterns).filter(files) 12 console.log(filtered) 13})
.filter(paths: Array<Pathname>): Array<Pathname>
1type Pathname = string
Filters the given array of pathnames, and returns the filtered array.
- paths
Array.<Pathname>The array ofpathnames to be filtered.
.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): TestResult
New in 5.0.0
Returns TestResult
1// Since 5.0.0 2interface TestResult { 3 ignored: boolean 4 // true if the `pathname` is finally unignored by some negative pattern 5 unignored: boolean 6 // The `IgnoreRule` which ignores the pathname 7 rule?: IgnoreRule 8} 9 10// Since 7.0.0 11interface IgnoreRule { 12 // The original pattern 13 pattern: string 14 // Whether the pattern is a negative pattern 15 negative: boolean 16 // Which is used for other packages to build things upon `node-ignore` 17 mark?: string 18}
{ignored: true, unignored: false}: thepathnameis ignored{ignored: false, unignored: true}: thepathnameis unignored{ignored: false, unignored: false}: thepathnameis never matched by any ignore rules.
.checkIgnore(target: string): TestResult
new in 7.0.0
Debugs gitignore / exclude files, which is equivalent to git check-ignore -v. Usually this method is used for other packages to implement the function of git check-ignore -v upon node-ignore
- target
stringthe target to test.
Returns TestResult
1ig.add({ 2 pattern: 'foo/*', 3 mark: '60' 4}) 5 6const { 7 ignored, 8 rule 9} = checkIgnore('foo/') 10 11if (ignored) { 12 console.log(`.gitignore:${result}:${rule.mark}:${rule.pattern} foo/`) 13} 14 15// .gitignore:60:foo/* foo/
Please pay attention that this method does not have a strong built-in cache mechanism.
The purpose of introducing this method is to make it possible to implement the git check-ignore command in JavaScript based on node-ignore.
So do not use this method in those situations where performance is extremely important.
static isPathValid(pathname): boolean since 5.0.0
Check whether the pathname is an valid path.relative()d path according to the convention.
This method is NOT used to check if an ignore pattern is valid.
1import {isPathValid} from 'ignore' 2 3isPathValid('./foo') // false
.addIgnoreFile(path)
REMOVED in 3.x for now.
To upgrade ignore@2.x up to 3.x, use
1import fs from 'fs' 2 3if (fs.existsSync(filename)) { 4 ignore().add(fs.readFileSync(filename).toString()) 5}
instead.
ignore(options)
options.ignorecase since 4.0.0
Similar as the core.ignorecase option of git-config, node-ignore will be case insensitive if options.ignorecase is set to true (the default value), otherwise case sensitive.
1const ig = ignore({ 2 ignorecase: false 3}) 4 5ig.add('*.png') 6 7ig.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 ignore@4.x. If options.allowRelativePaths is true, ignore will not check whether the given path to be tested is path.relative()d.
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
1ignore({ 2 allowRelativePaths: true 3}).ignores('../foo/bar.js') // And it will not throw
Upgrade Guide
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
1.ignores(pathname: Pathname): boolean 2 3.filter(pathnames: Array<Pathname>): Array<Pathname> 4 5.createFilter(): (pathname: Pathname) => boolean 6 7.test(pathname: Pathname): {ignored: boolean, unignored: boolean}
See the convention here for details.
If there are invalid pathnames, the conversion and filtration should be done by users.
1import {isPathValid} from 'ignore' // introduced in 5.0.0 2 3const paths = [ 4 // invalid 5 ////////////////// 6 '', 7 false, 8 '../foo', 9 '.', 10 ////////////////// 11 12 // valid 13 'foo' 14] 15.filter(isPathValid) 16 17ig.filter(paths)
Upgrade 3.x -> 4.x
Since 4.0.0, ignore will no longer support node < 6, to use ignore in node < 6:
1var ignore = require('ignore/legacy')
Upgrade 2.x -> 3.x
- All
optionsof 2.x are unnecessary and removed, so just remove them. ignore()instance is no longer anEventEmitter, and all events are unnecessary and removed..addIgnoreFile()is removed, see the .addIgnoreFile section for details.
Collaborators
- @whitecolor Alex
- @SamyPesse Samy Pessé
- @azproduction Mikhail Davydov
- @TrySound Bogdan Chadkin
- @JanMattner Jan Mattner
- @ntwb Stephen Edgar
- @kasperisager Kasper Isager
- @sandersn Nathan Shively-Sanders
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
30 commit(s) and 6 issue activity found in the last 90 days -- score normalized to 10
Reason
no binaries found in the repo
Reason
0 existing vulnerabilities detected
Reason
license file detected
Details
- Info: project has a license file: LICENSE-MIT:0
- Warn: project license file does not contain an FSF or OSI license.
Reason
Found 1/11 approved changesets -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/nodejs.yml:1
- Info: no jobLevel write permissions found
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/nodejs.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/kaelzhang/node-ignore/nodejs.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/nodejs.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/kaelzhang/node-ignore/nodejs.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/nodejs.yml:43: update your workflow using https://app.stepsecurity.io/secureworkflow/kaelzhang/node-ignore/nodejs.yml/master?enable=pin
- Warn: npmCommand not pinned by hash: .github/workflows/nodejs.yml:28
- Info: 0 out of 2 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 1 third-party GitHubAction dependencies pinned
- Info: 0 out of 1 npmCommand dependencies pinned
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'master'
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 21 are checked with a SAST tool
Score
4.3
/10
Last Scanned on 2025-01-27
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More