ignored v2.0.4

ignored

Get a list of entries from .gitignore file.

Why?

In the faster project we are watching directories for changes,
but we want to ignore the files/directories listed in the .gitignore file.

There were a couple of options parsing .gitignore files on NPM see Research section below,
but none were as simple or well-tested as we needed, so we wrote our own.

And because it's fast, has zero dependencies and (might be) useful to others, we have released it as an npm package!

What?

This ultra-simple module parses your .gitignore file and gives you an list (array) of the items it finds.

Usage

Install from NPM

npm install ignored --save

In Your Code

var ignored = require('ignored')(__dirname+'/../.gitignore'); // use .gitignore in parent dir
console.log(ignored); // use the array of .gitignore entries as desired

We recommend using this module Synchronously once at the top of your file (it only gets run once at the start-up of your project and only
takes a couple of milliseconds, similar to a require call).

There are actually 3 ways to use this module in your code:

1. Sync (Without passing a .gitignore file as parameter)

The simplest way to use this module is to let it figure out where your project's .gitignore
file is and return the list synchronously at the top of your script.

// synchronous immediate invocation assigns the list to the ignored var directly
var ignored = require('ignored')(); // without param (we search for .gitignore)
// use the array of .gitignore entries as desired

Note: we only go one directory level up from the Current Working Directory as most
node projects have a shallow directory structure e.g. put code in a lib/ or src/.

2. Sync (Specifying a .gitignore file as the only parameter)

This is the recommended way of using the module as you know exactly
which .gitignore file you are using (some projects have multiple .gitignore files!)

// synchronous immediate invocation with a specific file supplied the only param
var ignored = require('ignored')('../.gitignore'); // use .gitignore in parent dir
// use the array of .gitignore entries as desired

3. Async (Specifying the .gitignore file as first parameter)

// async passing in a specific .gitignore file:
var ignored = require('ignored')
// use .gitignore in parent directory
ignored('../.gitignore', function callback(err, list) {
  if(err){
    console.log(err); // handle errors in your preferred way.
  }
  else {
    console.log(list); // use the array of directories as required.
  }
});
// use the array of .gitignore entries as desired

Contributing

All contributions are welcome.
We have done our best to make this module functional, simple and easy to understand.
If you spot an inefficiency or omission in the parser, please help us fix it!
(please create an issue to inform us!)

If anything is unclear please create an issue so we can help clarify.

devDependencies

Feel free to submit a Pull Request if these are out of date. (thanks!)

Research

As always with NPM, there are many available modules that could do what we want:

So we tried a few:

• fstream-ignore: https://www.npmjs.com/package/fstream-ignore (streaming is great, but complicates things here...)
• ignore: https://www.npmjs.com/package/ignore (way too many options! no simple "no-brainer" usage)
• gitignore-parser: https://www.npmjs.com/package/gitignore-parser (strange interface and lacks documentation)
• parse-gitignore: https://www.npmjs.com/package/parse-gitignore (no async method/interface and expects you to supply the .gitignore file contents)

(Once again) none of these were simple, (sufficiently) well-tested or clearly documented for our liking.