Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status NPM version

Monitor a directory for changes. You can detect file changes, creations, deletions and renames. You know it works because it actually has tests!


Via NPM: npm install gargoyle


There is one export: gargoyle.monitor(path[, options, callback]). path should be a filename (file or directory). IF it's a directory, it'll be traversed recursively.

When something changes, it'll emit one of the following events:

  • modify - when a file is modified
  • create - when a file is created
  • delete - when a file is deleted
  • rename - when a file is renamed (only when options.type === "watch")

Your event listener should be a function that takes one argument: the absolute path of the file that got modified/created/deleted/renamed.


Monitor a directory tree:

var gargoyle = require('gargoyle');
gargoyle.monitor('/some/dir', function(err, monitor) {
	if (err) {

	//monitor is an EventEmitter with the following properties:
	//  files is a hash of filename -> FSWatcher

	monitor.on('modify', function(filename) {
		console.log(filename + ' was modified');
	monitor.on('delete', function(filename) {
		console.log(filename + ' was deleted');
	monitor.on('create', function(filename) {
		console.log(filename + ' was created');

	//only when options.type === "watch"
	monitor.on('rename', function(filename) {
		console.log(filename + ' was renamed');

Stop monitoring:

monitor.stop(function() {
	console.log('watchers stopped');

//monitor is now worthless


There are a few different options you can pass as an optional second parameter to gargoyle.monitor.

Exclude certain files

var path = require('path');
var options = {
	exclude: function(filename, stat) {
		//note: filename is absolute
		var basename = path.basename(filename);

		//ignore dotfiles
		if (basename.charAt(0) === '.') {
			return true;

		//ignore the static directory
		if (stat.isDirectory() && basename === 'static') {
			return true;

		//javascript/coffeescript files are okay
		if (!/\.(js|coffee)$/.test(basename)) {
			return true;

		return false;
gargoyle.monitor('/some/dir', options, function(err, monitor) {

Watch type

Use fs.watchFile instead of If you're on OS X, or trying to watch a network directory (e.g. a shared folder in a VM), you'll want to use fs.watchFile. is far more efficient, and much faster, but doesn't work all the time.

var options = {
	type: 'watchFile' //default is 'watch'
gargoyle.monitor('/some/dir', options, function(err, monitor) {

Poll interval

If you use the watchFile type, you can define the poll interval for stating the filesystem (this is part of the watchFile Node API). The default is 507, which is 10x as fast as the Node default.

var options = {
	type: 'watchFile',
	interval: 50 //poll 20 times a second
gargoyle.monitor('/some/dir', options, function(err, monitor) {


git clone
cd gargoyle
npm install
npm test

When running the tests, you'll notice the fs.watchFile tests take much longer. This is due to the fact that some file systems do not have millisecond resolution, which means we have to wait at least one second to detect a modification.


Monitor a directory for changes. Like a gargoyle.



No packages published
You can’t perform that action at this time.