? in a pattern should match a single character. Eg. .*.sw? should ignore .testfile.swo. It's missing from the documentation page you link to for the spec (https://git-scm.com/docs/gitignore), but it is in https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#Ignoring-Files, and it is the functionality that git (git status) follows.

11:05:09 j ~/Development/ls-ignore [master] $ git status
On branch master
Your branch is up-to-date with 'origin/master'.

nothing to commit, working tree clean
11:05:11 j ~/Development/ls-ignore [master] $ cat .gitignore
*~
node_modules
yarn*
11:05:21 j ~/Development/ls-ignore [master] $ touch test.swo
11:05:31 j ~/Development/ls-ignore [master]?1 $ git status
On branch master
Your branch is up-to-date with 'origin/master'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        test.swo

nothing added to commit but untracked files present (use "git add" to track)
11:05:35 j ~/Development/ls-ignore [master]?1 $ echo "*.sw?" >> .gitignore
11:05:40 j ~/Development/ls-ignore [master]≠1 $ cat .gitignore
*~
node_modules
yarn*
*.sw?
11:05:51 j ~/Development/ls-ignore [master]≠1 $ git status
On branch master
Your branch is up-to-date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   .gitignore

no changes added to commit (use "git add" and/or "git commit -a")

> nore = ignore().add(['.*.sw?'])
IgnoreBase {
  _rules: 
   [ { origin: '.*.sw?',
       pattern: '.*.sw?',
       negative: false,
       regex: /(?:^|\/)\.[^\/]*\.sw\?(?=$|\/)/i } ],
  _cache: {},
  _added: true,
  [Symbol(node-ignore)]: true }
> nore.filter(['.this.swo'])
[ '.this.swo' ]
> nore.ignores(['.this.swo'])
false

Using the star * to match everything and then negating certain patterns doesn't work and returns an empty array.

const paths = ["modules/ignore", "modules/include"];
const globs = ["*", "!modules/include"];
const filtered = ignore().add(globs).filter(paths);
// filtered == []

If however one uses */* it does.

const paths = ["modules/ignore", "modules/include"];
const globs = ["*/*", "!modules/include"];
const filtered = ignore().add(globs).filter(paths);
// filtered == ["modules/include"]

See here: https://codepen.io/abemedia/pen/JjNBvOR?editors=1111

According to the spec:

An optional prefix "!" which negates the pattern; any matching file excluded by a previous pattern will become included again. It is not possible to re-include a file if a parent directory of that file is excluded.

Given:

var ignore = require('ignore');
var ig = ignore().addPattern(['/abc/', '!/abc/a.js']);
var paths = ['abc/a.js', 'abc/d/e.js'];
ig.filter(paths);

Output:

[ 'abc/a.js' ]

Expected:

[]

The example provided in the README no longer works correctly with the latest version (3.0.3).

For example, if I run the following code:

var ignore = require("ignore");
var path = require("path");

var ig = ignore().addPattern([".abc/*", "!.abc/d/*"]);

var paths = [
    path.normalize(".abc/a.js"),
    path.normalize(".abc/d/e.js")
];

console.log("paths:   ", paths);
console.log("filtered:", ig.filter(paths));

Actual Result

2.2.19:

paths:    [ '.abc/a.js', '.abc/d/e.js' ]
filtered: [ '.abc/d/e.js' ]

3.0.3:

paths:    [ '.abc/a.js', '.abc/d/e.js' ]
filtered: []

Expected:

The result from 2.2.19. Because of the splat in the first pattern, the negating pattern should be able to override it. This is in contrast to the issue in #10, whereby the entire folder is ignored without a splat.

related to #5

First thank you for making such a sick library!

https://runkit.com/neeksandhu/runkit-npm-ignore

Snippet above shows how dist/* matches dist/index.js but won't match dist\build.

A windows path being matched against a unix glob that is.

As we all know, and as mentioned in one of the previous issues here, almost all applications and programs just work given above scenario; windows paths <-> unix paths

I think there aren't any side effects if ignore is made platform agnostic as far as type of slashes are concerned.

We can very well remove process.platform === 'win32' thing in code just by using [\/\\]+ instead.

I'm trying to use ignore in a webapp where I'd love to have this feature :)

Both add and ignore accept an array. However, the type definitions specify that it has to be a writable array. For example:

I think read-only input is a valid use case, is it not? If so, I'd be happy to implement a small PR for this.

In order to use this in a watch mode tool, we need to be able to remove and replace rules whenever a .gitignore file is changed or even deleted.

I was upgrading to v5 in stylelint and turns out isPathValid doesn't validate Windows paths correctly.

isPathValid('..\\foo') // → true, but should be false

This is very minor but I'm just thinking about edge cases in guaranteeing I fully emulate git's behavior. Git seems to ignore any rules with .. as a path element, but ignore doesn't when testing a similarly relative path.

Also i.ignores('../foo') will error since the path starts with ../, but it won't error on /../ in the middle of the path.

> var i = require("ignore").default()
> i.add('test/../*')
> i.ignores('foo')
false
> i.ignores('test/../foo')
true

Whereas with this rule in .gitignore, and existing directory test and file foo in the root dir:

$ git check-ignore foo || echo not ignored
not ignored
$ git check-ignore test/../foo || echo not ignored
not ignored

• fixes fnmatch(3) and glob(3)
• make symbol non-enumerable
• eslint
• mocha -> tap
• remove support for node < 6 by default
• supports wildcard ?
• supports *.[oa] (range)
• supports [a-z] (character set)
• [a-9] special cases: range out of order
• special range: [0-z]
• ignorecase?
• update index.d.ts

Using the whitelisting pattern from https://jasonstitt.com/gitignore-whitelisting-patterns of

# Ignore everything, then add specific subtrees example
*
!*/
!/nested/file/to/whitelist

doesn't seem to work.

Example:

var ignore = require("ignore");
const ig = ignore().add(['*', '!*/', '!/foo/bar']);
const results = ['a','b/c','b/d/','foo/e','foo/bar'].forEach(p => {
  console.log([p, ig.ignores(p)]);
});
// [ 'a', true ]
// [ 'b/c', false ] this should be true
// [ 'b/d/', false ]
// [ 'foo/e', false ] this should be true
// [ 'foo/bar', false ]

related to #36

This package is used by various tools for parsing an ignore file. Since basically every tool, especially linter, simply needs to ignore files from .gitignore, and maybe some other files, it would be nice if they could simply include the file list from .gitignore.

In the Google Cloud SDK, this is solved using the following syntax:

#!include:.gitignore

See https://cloud.google.com/sdk/gcloud/reference/topic/gcloudignore

Currently Prettier, ESLint, and Stylelint all use separate ignore, all parsed using this package. All of their ignore files typically contain the same content.

I'm using the ESLint no-restricted-imports rule, which uses this package under the hood. I've reproduced this issue against node-ignore directly.

We have some tokens in our import paths which are denoted by square brackets. Ignoring these doesn't currently seem to work. I've escaped them in the pattern as required by gitignore (and another \ to escape the \ for JavaScript), and tried the same scenario using git check-ignore which works.

it('ignores patterns containing square brackets', () => {
  const ignorer = ignore().add(['src/\\[app\\]']);

  expect(ignorer.ignores('src/[app]')).toBe(true); // fails
});

Such paths also can't be un-ignored:

it('un-ignores negated patterns containing square brackets', () => {
  const ignorer = ignore().add(['src/**', '!src/\\[app\\]']);

  expect(ignorer.ignores('src/a')).toBe(true);
  expect(ignorer.ignores('src/[app]')).toBe(false); // fails
});

Version: 5.1.4

Node ignore is treating . as a special character and escaping it.

I am wondering why this is being done? I have looked at the gitignore docs and the glob docs, and cannot find a reference to . having a special meaning.

gitignore:

node_modules/*
!node_modules

then,

node_modules/a.js should be ignored.

might involve completely refractors

Example:

const ignore = require("ignore");

let ig = ignore().add(['/abc/']) // directory in the beginning of the pathname called "abc"
ig.ignores('./abc/'); // returns false although true is expected

This works as expected using git check-ignore:

mkdir /tmp/foobar
cd /tmp/foobar
git init
echo "/abc/" > .gitignore
git check-ignore ./abc/ # returns ./abc/

I have an .npmignore file like this:

# Ignore everything
**
# Bring back just the "dist" folder
!/dist/**

When I do npm pack, NPM selects everything under the "dist" folder.

Whereas node-ignore does not seem to reflect this behavior:

let ig = require('ignore')();
ig.add("**");
ig.add("!/dist/**");

# --> prints: true
ig.ignores("dist/bundle.js")

Thank you very much for this awesome library!

I think a write-up on the difference of gitignore rules and minimatch rules would further explain why this library is necessary.

Another reason is that I want to improve how globby does globbing with ignoring gitignore patterns and only if there is a translator between these two rules sets. If you can implement yourself, that would be perfect! If not, any documentation of how it should be would be very helpful!

Following the eslint documentation I was playing around with the --ignore-pattern argument and noticed patterns with a negative and a glob were not being ignored.

I created a failing test, I can submit it as a PR if it's needed

[
  'negative with a double glob', [
    '!**/*.{test,mock}.js'
  ], {
    'a.js': 1,
    'a.test.js': 0,
    'a.mock.js': 0,
    'src/a.js': 1,
    'src/a.test.js': 0,
    'src/a.mock.js': 0,
  }
]

I notice you have a lot of similar issues related to windows paths. This one is specifically relative paths:

On unix, this throws an error.
cwd is /mnt/c/module

ignore.ignores('/mnt/c/module/package.json')

fatal error RangeError: path should be a `path.relative()`d string, but got "/mnt/c/module/package.json"

On windows it behaves differently. Possibly a false positive, but there's no error:

cwd is C:\module

ignore.ignores('C:\module\package.json')

When using node-glob-gitignore, in specific circumstances I'll describe just after the line below fails and ignore rules gets ignored.

When does it fails ?

Seems related to npm duplicating the dependency to ignore in my module and node-glob-gitignore. I end up with my node_modules structure having two different ignore directory and thus my instances differs what node-glob-gitignore is expecting.

Suggested fix

if (pattern instanceof IgnoreBase) { 

Would become

if (pattern && '_rules' in pattern) {

• fixes excludes issues, related to #10

The pattern **folder is currently not respected. This pattern is not documented in the official git documentation here https://git-scm.com/docs/gitignore but is enforced by git and is different from the pattern **/folder.

The difference

**/subfolder \n
!folder/subfolder/testFile.txt

Will ignore the folder subfolder and the negation pattern will not work, as explained in the gitignore documentation.

It is not possible to re-include a file if a parent directory of that file is excluded.

While with those lines the file folder/subfolder/testFile.txt will be re-included as the pattern **subfolder does not match the folder subfolder but any file containing the string subfolder.

**subfolder
!folder/subfolder/testFile.txt

Actual behaviour:

const ignore = require('ignore') ;
const ig = ignore().add(['**subfolder']);

let isIgnored = ig.ignores('folder/subfolder/testFile.txt') // false

const ignore = require('ignore') ;
const ig = ignore().add(['**/subfolder']);

let isIgnored = ig.ignores('folder/subfolder/testFile.txt') // true

Expected behaviour

const ignore = require('ignore') ;
const ig = ignore().add(['**subfolder']);

let isIgnored = ig.ignores('folder/subfolder/testFile.txt') // true

const ignore = require('ignore') ;
const ig = ignore().add(['**/subfolder']);

let isIgnored = ig.ignores('folder/subfolder/testFile.txt') // true

Hi, would it be possible to add a license file the npm distribute package ? If you're not including the full license text it's almost impossible to use this library in various environments.

Thank you

We use addIgnoreFile in ESLint to load in our .eslintignore files, but it was removed in version 3.0.0. Are you planning to re-add this method, as your comment in #10 (comment) seems to indicate?

Another silly edge case. Unsurprisingly, it seems a .gitignore file can't ignore itself, but it can ignore other .gitignore files. For example the rule .gitignore won't ignore the file containing it, but it will ignore .gitignore files in subdirectories.

Since ignore only deals with rules, if one naively loads all the rules from a .gitignore file into it, ignore will think that .gitignore file is itself ignored. Especially in the worst case that there is a * rule followed by negative rules, but not !.gitignore.

I think we should add a warnings section to the README about pitfalls like this.

git has its stuff in directory .git, so i guess users of git wont have to add .git to .gitignore cause git ignores it by default.

so, should this library also ignore .git by default? (v5.0.2 does not)
or should we add .git entry to our .gitignore?

The README file is currently marked as executable.

chmod a-x ./README.md

const ignore = require('ignore')

// Patterns copied straight from the last example at the very end of
// https://git-scm.com/docs/gitignore
const ig = ignore().add([
  '# exclude everything except directory foo/bar',
  '/*',
  '!/foo',
  '/foo/*',
  '!/foo/bar',
])

const paths = [
  'no.js',
  'foo/no.js',
  'foo/bar/yes.js',
  'foo/bar/baz/yes.js',
  'boo/no.js',
]

console.log(ig.filter(paths))
// Actual: []
// Expected: ['foo/bar/yes.js', 'foo/bar/baz/yes.js']

ignore version: 3.2.0

Why does this module nest in a node_modules folder inside the folder of a dependency in the main node_modules folder? The new behavior since npm 3.11 or something was that all the dependency would be in the main node_modules folder, no more nesting. Why does ignore not adhere to this standard?

I think node-ignore should not filter relative paths starting with ./ or ../

const ignore = require('ignore');
var ig = ignore().add(['.*']);
ig.filter(['foo', '.bar', './baz', '../quuz']);

Outputs: [ 'foo' ]

Similarly, relative ignore paths should be discarded as invalid:

const ignore = require('ignore')
var ig = ignore().add(['../*'])
ig.filter(['foo', '.bar', './baz', '../quuz'])
[ 'foo', '.bar', './baz' ]

Given the following reproduction:

mkdir /tmp/ignoretest
cd /tmp/ignoretest

mkdir foo
touch foo/bar.js

echo > .gitignore <<'EOT'
/*/
!/foo/
EOT

git init
git add .
git status

The foo/bar.js file got added to the repository. Doing the same on ignore, however:

const ignore = require(`ignore`);

ignore().add([
  `/*/`,
  `!/foo/`,
]).ignores(`foo/bar.js`) // true

Related #33

I understand that paths need to be relative to the working directory, but how do I check the working directory itself?

If I use path.relative(process.cwd(), process.cwd()) I get an empty string which is also invalid for checking.

If it is impossible to ignore the working directory I could add an if statement to don't check that case, but I am not sure if it is not possible to create a rule to skip the working directory.

And what about parent directories to the working directory, for example, ../.. should those paths have a special treatment too? Be discarded because they are invalid in terms of git ignore files?

I need to implement hierarchical .gitignore files for my application, and I've run into an issue trying to combine the results of multiple rulesets. My approach has been to walk down the pathname and apply .gitignore files successively.¹ However, with the current API I cannot tell whether a file is merely "not ignored" or is actually "unignored".

Here's a specific scenario:

// In real life this would be wrapped in a loop or recursion,
// I'm just hard-coding variables for demonstration purposes

rootRules = ignore().add(readFileSync('.gitignore', 'utf8')) // contains 'foo.txt'
rootIgnoredA = rules.ignores("/A/foo.txt") // true
rootIgnoredB = rules.ignores("/B/foo.txt") // true

ARules = ignore().add(readFileSync('A/.gitignore', 'utf8')) // is empty
BRules = ignore().add(readFileSync('B/.gitignore', 'utf8')) // contains '!foo.txt'
ignoredA = ARules.ignores("/A/foo.txt") // false
ignoredB = BRules.ignores("/B/foo.txt") // also false

Given the result values of both .gitignore files, there's not enough information to determine the combined result. "/A/foo.txt" should be ignored, but "/B/foo.txt" should NOT be ignored, because it was unignored.

I think the cleanest way to solve this would be to allow specifying an starting value to .ignores. Like:

ignoredA = ARules.ignores("/A/foo.txt", rootIgnoredA) // true
ignoredB = BRules.ignores("/B/foo.txt", rootIgnoredB) // false

But I would also be OK with a new function that returned a ternary value, like true/null/false or "ignored"/"nochange"/"unignored".

It's a good practice to add git tag for every version.
Here's good util
https://github.com/sindresorhus/np/blob/master/np.sh

Hi @kaelzhang ,

my filter:
.git
!.git/config
.ftpconfig

0: Object
    negative: false
    origin: ".git"
    pattern: ".git"
    regex: /(?:^|\/)\.git(?=$|\/)/i
1: Object
    negative: true
    origin: "!.git/config"
    pattern: ".git/config"
    regex: /^\.git\/config(?=$|\/$)/i
2: Object
    negative: false
    origin: ".ftpconfig"
    pattern: ".ftpconfig"
    regex: /(?:^|\/)\.ftpconfig(?=$|\/)/i

I use the ignores function, but result (cache):
D:/ => true
D:/DEV/ => true
D:/DEV/test/ => true
D:/DEV/test/.git/ => false
D:/DEV/test/.git/COMMIT_EDITMSG => false
D:/DEV/test/.git/packed-refs => false
D:/DEV/test/.git/config => false || False positive, because this is negative rule!

related to #27

Hi,
I use your plugin in my project. My Project is located in c:\programming\test.
I have a .ignore file in my folder root which is used by ignore like follows:

this.ignore.add(readFileSync(join(path.fsPath, ".ignore")).toString());

if( this.ignore.ignores("c:/programming/test/includes/test.log") === false )
  doSomething();

The content of my .ignore File is

*.*
!*.log

But this does ignore all files. How can I make this work?

Just added a .gitignore file containing the following rules:

# git-ls-files --others --exclude-from=.git/info/exclude
# Lines that start with '#' are comments.
# For a project mostly in C, the following would be a good set of
# exclude patterns (uncomment them if you want to use them):
# *.[oa]
# *~
/.project
/.settings
/sharedTools/external/*
Thumbs.db
/packs
*.pyc
/.cache
/bigtxt
.metadata/*
*~
/sharedTools/jsApiLua.lua
._*
.DS_Store
/DISABLED
/.pydevproject
/testbox
*.swp
/packs/packagesTree
/packs/*.ini
.buildpath
/resources/hooks/*
.idea
.idea/*
/tags
**.iml
.sonar/*

And none of those files are being ignored. For example if I take out the leading slash in '/packs', it correctly ignores the packs directory.

Also, the following rules in a submodule are not working either, .js files are being ignored!

*~
._*
.DS_Store
*.pyc
.idea
.idea/*
.*.sw?

Am I doing something wrong? Do I need to send the full file path or just the base name when filtering?

Well in gitignore i can use this kind of expression and its very usefull:

directory/**/*.js

Find all the js files in directory folder and all the directory childs too.

This works:

const ignore = require('ignore')
var ig = ignore().add(['foo/*', '!foo/bar.js'])
ig.filter(['foo/bar.js'])
[ 'foo/bar.js' ]

This doesn't:

const ignore = require('ignore')
var ig = ignore().add(['foo/**', '!foo/bar.js'])
ig.filter(['foo/bar.js'])
[]

according to the gitignore spec, more than two asterisks ** should not be valid, so something like .abc/***** should not be allowed. However, ignore.isPathValid('.abc/*****') returns true.