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