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.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.
Table Of Main Contents
- Usage
- Pathname Conventions
- See Also:
- glob-gitignore matches files using patterns and filters them
according to gitignore rules.
- Upgrade Guide
Install
npm i ignore
Usage
import ignore from 'ignore'
const ig = ignore().add(['.abc/*', '!.abc/d/'])
Filter the given paths
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
paths.filter(ig.createFilter()); // ['.abc/d/e.js']
Win32 paths will be handled
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's 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, 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.
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:
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 ignore@2.x up to 3.x, use
import fs from 'fs'
if (fs.existsSync(filename)) {
ignore().add(fs.readFileSync(filename).toString())
}
instead.
.filter(paths: Array<Pathname>): Array<Pathname>
type Pathname = string
Filters the given array of pathnames, and returns the filtered array.
- paths Array.<Pathname> The array of pathnames 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,
// 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:
[
'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:
// 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 with option.mark = true to fetch the
structure of the current directory:
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.
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
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 ignore.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.
ignore.isPathValid('./foo') // false
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.
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
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
ignore({
allowRelativePaths: true
}).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
.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 for details.
If there are invalid pathnames, the conversion and filtration should be
done by users.
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:
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, 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
Generated by dwww version 1.15 on Fri May 24 01:25:15 CEST 2024.