# File-grained cross-platform FS monitoring for Node.js

**Wait, wait, how's it different from `fs.watch`?** Unlike `fs.watch`, fsmonitor:

* monitors an entire subtree (`fs.watch` only monitors a single folder)
* gives you the entire list of added, removed and modified files and folders (e.g. when you add or delete a non-empty folder, the change event will contain a list of all files in that folder)

Here's what happens when you call `fsmonitor.watch(path)`:

* The specified file system subtree is scanned, and the stat data is kept in memory.
* `fs.watch` is called to start monitoring every subfolder encountered.
* When change events are reported, the subtree is rescanned to determine the list of changes.
* `fs.watch` is called for the new subfolders, and the watchers are shut down for the removed ones.


## Status

Alpha stage. Seems to work, waiting for feedback, shipping as part of LiveReload 0.5 for Windows.

Planned features:

* only reporting changes in the files matching .gitignore-style masks you specify (using pathspec module for handling masks)
* more efficient native code implementations on Mac and Windows
* offloading per-folder monitoring backends to child processes to avoid hitting the limit on the number of file handles


## Installation

    npm install fsmonitor

or, to use fsmonitor command-line tool (see below):

    npm install -g fsmonitor


## Usage

    fsmonitor = require('fsmonitor');
    fsmonitor.watch('/some/folder', null, function(change) {
        console.log("Change detected:\n" + change);  # has a nice toString

        console.log("Added files:    %j", change.addedFiles);
        console.log("Modified files: %j", change.modifiedFiles);
        console.log("Removed files:  %j", change.removedFiles);

        console.log("Added folders:    %j", change.addedFolders);
        console.log("Modified folders: %j", change.modifiedFolders);
        console.log("Removed folders:  %j", change.removedFolders);
    });

    var monitor = fsmonitor.watch('.', {
        // include files
        matches: function(relpath) {
            return relpath.match(/\.js$/i) !== null;
        },
        // exclude directories
        excludes: function(relpath) {
            return relpath.match(/^\.git$/i) !== null;
        }
    });
    monitor.on('change', function(changes) {
        console.log(changes);
    });


## Command-line tool

Includes a command-line tool that can report changes and/or run a specified command on every change.

For example, to invoke `npm test` when any JavaScript file is modified:

    fsmonitor -s -p '+*.js' npm test

Usage:

    Usage: fsmonitor [-d <folder>] [-p] [-s] [-q] [<mask>]... [<command> <arg>...]

    Options:
      -d <folder>        Specify the folder to monitor (defaults to the current folder)
      -p                 Print changes to console (default if no command specified)
      -s                 Run the provided command once on start up
      -q                 Quiet mode (don't print the initial banner)

    Masks:
      +<mask>            Include only the files matching the given mask
      !<mask>            Exclude files matching the given mask

      If no inclusion masks are provided, all files not explicitly excluded will be included.

    General options:
      --help             Display this message
      --version          Display fsmonitor version number


## Unit test

Install necessary modules:

    npm install

Start `npm test` to run the unit tests:

    npm test