Gitignore Parser

A simple yet complete .gitignore parser for node.js.

Installation

npm install @gerhobbelt/gitignore-parser

Features

Supports all features listed in the GIT SCM gitignore manpage:

• handles the ** wildcard anywhere

  • in both the usual usage, e.g. foo/**/bar, and also in complexes such as yo/**la/bin
  • can be used multiple times in a single pattern, e.g. foo/**/rec**on

• handles the * wildcard

• handles the ? wildcard

• handles [a-z] style character ranges

• understands !-prefixed negated patterns

• understands \#, \[, \\, etc. filename escapes, thus handles patterns like \#*# correctly (hint: this is NOT a comment line!)

• deals with any sequence of positive and negative patterns, like this one from the .gitignore manpage:

  # exclude everything except directory foo/bar
  /*
  !/foo
  /foo/*
  !/foo/bar
  

• handles any empty lines and # comment lines you feed it

• we're filename agnostic: the ".gitignore file" does not have to be named .gitignore but can be named anything: this parser accepts .gitignore-formatted content from anywhere: you load the file, we do the parsing, you feed our accepts() or denies() APIs any filenames / paths you want filtered and we'll tell you if it's a go or a no go.

• extra: an additional API is available for those of you who wish to have the complete and utter .gitignore experience: use our inspects(path) API to know whether the given gitignore filter set did actively filter the given file or did simple allow it to pass through.

  Read as: if the .gitignore has a pattern which matches the given file/path, then we will return true, otherwise we return false.

  Use this in directory trees where you have multiple .gitignore files in nested directories and are implementing tooling with git-like .gitignore behaviour.

Usage

1var parser = require('@gerhobbelt/gitignore-parser'),
2    fs = require('fs');
3
4var gitignore = parser.compile(fs.readFileSync('.gitignore', 'utf8'));
5
6gitignore.accepts('LICENSE.md') === true;
7gitignore.denies('LICENSE.md') === false;
8gitignore.inspects('LICENSE.md') === false;
9
10gitignore.accepts('node_modules/mocha/bin') === false;
11gitignore.denies('node_modules/mocha/bin') === true;
12gitignore.inspects('node_modules/mocha/bin') === true;
13
14gitignore.accepts('foo/bar') === true;
15gitignore.denies('foo/bar') === false;
16gitignore.inspects('foo/bar') === true; // <-- as there's a negated pattern `!foo/bar` addressing this one
17
18
19var files = [
20  '.gitignore',
21  '.travis.yml',
22  'LICENSE.md',
23  'README.md',
24  'package.json',
25  'lib/index.js',
26  'test/index.js',
27  'test/mocha.opts',
28  'node_modules/mocha/bin/mocha',
29  'node_modules/mocha/README.md'
30];
31
32// produce only files that are not gitignored
33let list = files.filter(gitignore.accepts);
34
35// produce only files that *are* gitignored
36let list = files.filter(gitignore.denies);

Notes

• As the .gitignore spec differentiates between patterns such as foo and foo/, where the latter only matches any directory named foo, you MUST pass the is-this-a-file-or-a-directory info to us when you invoke any of our accepts(), denies() and inspects() APIs by making sure directory paths have a trailing /.

  When you feed us straight from glob(), you can accomplish this in the quickest possible way by using the glob() mark option which auto-postfixes a / to each directory it produces.

See also

TBD

https://github.com/isaacs/node-glob

License

Apache 2, see LICENSE.md.