Linux | OS X | Windows | Coverage | Downloads |
---|---|---|---|---|
|
|
|
|
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.
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.
- Usage
Pathname
Conventions- See Also:
glob-gitignore
matches files using patterns and filters them according to gitignore rules.
- Upgrade Guide
npm i ignore
import ignore from 'ignore'
const ig = ignore().add(['.abc/*', '!.abc/d/'])
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
paths.filter(ig.createFilter()); // ['.abc/d/e.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']
-
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, soignore
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
.
- '
- pattern
String | Ignore
An ignore pattern string, or theIgnore
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.
REMOVED in 3.x
for now.
To upgrade [email protected]
up to 3.x
, use
import fs from 'fs'
if (fs.existsSync(filename)) {
ignore().add(fs.readFileSync(filename).toString())
}
instead.
type Pathname = string
Filters the given array of pathnames, and returns the filtered array.
- paths
Array.<Pathname>
The array ofpathname
s to be filtered.
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'
]
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)
})
new in 3.2.0
Returns Boolean
whether pathname
should be ignored.
ig.ignores('.abc/a.js') // true
Creates a filter function which could filter an array of paths with Array.prototype.filter
.
Returns function(path)
the filter function.
Returns TestResult
interface TestResult {
ignored: boolean
// true if the `pathname` is finally unignored by some negative pattern
unignored: boolean
}
{ignored: true, unignored: false}
: thepathname
is ignored{ignored: false, unignored: true}
: thepathname
is unignored{ignored: false, unignored: false}
: thepathname
is never matched by any ignore rules.
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
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
Which is alternative to options.ignoreCase
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.
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
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)
Since 4.0.0
, ignore
will no longer support node < 6, to use ignore
in node < 6:
var ignore = require('ignore/legacy')
- All
options
of 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.
- @whitecolor Alex
- @SamyPesse Samy PessΓ©
- @azproduction Mikhail Davydov
- @TrySound Bogdan Chadkin
- @JanMattner Jan Mattner
- @ntwb Stephen Edgar
- @kasperisager Kasper Isager
- @sandersn Nathan Shively-Sanders