Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Better file system watching for Node.js. Provides a normalised API the file watching APIs of different node versions, nested/recursive file and directory watching, and accurate detailed events for file/directory changes, deletions and creations.

v2.4.11. Bugfix.

- v2.4.11 February 7, 2014
	- Fixed interval option not beeing passed on to child watchers (regression since v2.4.7)
		- Thanks to [David Byrd](https://github.com/thebyrd) for [pull request #58](#58)
latest commit e493cc92f3
Benjamin Arthur Lupton balupton authored
Octocat-spinner-32 bin v2.3.7. Bugfix. Improvement. February 06, 2013
Octocat-spinner-32 src v2.4.11. Bugfix. February 07, 2014
Octocat-spinner-32 .gitignore v2.4.6. Improvement. December 18, 2013
Octocat-spinner-32 .npmignore v2.4.6. Improvement. December 18, 2013
Octocat-spinner-32 .travis.yml v2.4.10. Bugfix. February 07, 2014
Octocat-spinner-32 CONTRIBUTING.md v2.4.6. Improvement. December 18, 2013
Octocat-spinner-32 Cakefile Updated build files January 10, 2014
Octocat-spinner-32 HISTORY.md v2.4.11. Bugfix. February 07, 2014
Octocat-spinner-32 LICENSE.md v2.4.6. Improvement. December 18, 2013
Octocat-spinner-32 README.md v2.4.11. Bugfix. February 07, 2014
Octocat-spinner-32 package.json v2.4.11. Bugfix. February 07, 2014
README.md

Watchr — better file system watching for Node.js

Build Status NPM version Dependency Status Development Dependency Status
Gittip donate button Flattr donate button PayPayl donate button BitCoin donate button Wishlist browse button

Watchr provides a normalised API the file watching APIs of different node versions, nested/recursive file and directory watching, and accurate detailed events for file/directory creations, updates, and deletions.

Watchr is made to be a module that other tools include. If you are looking for a command line tool to perform actions when files are changed, check out Watchy.

You install it via npm install watchr and use it via require('watchr').watch(config). Available configuration options are:

  • path a single path to watch
  • paths an array of paths to watch
  • listener a single change listener to fire when a change occurs
  • listeners an array of listeners to fire when a change occurs, overloaded to accept the following values:
    • changeListener a single change listener
    • [changeListener] an array of change listeners
    • {eventName:eventListener} an object keyed with the event names and valued with a single event listener
    • {eventName:[eventListener]} an object keyed with the event names and valued with an array of event listeners
  • next (optional, defaults to null) a completion callback to fire once the watchers have been setup, arguments are:
    • when using the path configuration option: err, watcherInstance
    • when using the paths configuration option: err, [watcherInstance,...]
  • stat (optional, defaults to null) a file stat object to use for the path, instead of fetching a new one
  • interval (optional, defaults to 5007) for systems that poll to detect file changes, how often should it poll in millseconds
  • persistent (optional, defaults to true) whether or not we should keep the node process alive for as long as files are still being watched
  • catchupDelay (optional, defaults to 2000) because swap files delete the original file, then rename a temporary file over-top of the original file, to ensure the change is reported correctly we must have a delay in place that waits until all change events for that file have finished, before starting the detection of what changed
  • preferredMethods (optional, defaults to ['watch','watchFile']) which order should we prefer our watching methods to be tried?
  • followLinks (optional, defaults to true) follow symlinks, i.e. use stat rather than lstat
  • ignorePaths (optional, defaults to false) an array of full paths to ignore
  • ignoreHiddenFiles (optional, defaults to false) whether or not to ignored files which filename starts with a .
  • ignoreCommonPatterns (optional, defaults to true) whether or not to ignore common undesirable file patterns (e.g. .svn, .git, .DS_Store, thumbs.db, etc)
  • ignoreCustomPatterns (optional, defaults to null) any custom ignore patterns that you would also like to ignore along with the common patterns

The following events are available to your via the listeners:

  • log for debugging, receives the arguments logLevel ,args...
  • error for gracefully listening to error events, receives the arguments err
    • you should always have an error listener, otherwise node.js's behavior is to throw the error and possibly crash your application, see #40
  • watching for when watching of the path has completed, receives the arguments err, isWatching
  • change for listening to change events, receives the arguments changeType, fullPath, currentStat, previousStat, received arguments will be:
    • for updated files: 'update', fullPath, currentStat, previousStat
    • for created files: 'create', fullPath, currentStat, null
    • for deleted files: 'delete', fullPath, null, previousStat

To wrap it all together, it would look like this:

// Require
var watchr = require('watchr');

// Watch a directory or file
console.log('Watch our paths');
watchr.watch({
    paths: ['path1','path2','path3'],
    listeners: {
        log: function(logLevel){
            console.log('a log message occured:', arguments);
        },
        error: function(err){
            console.log('an error occured:', err);
        },
        watching: function(err,watcherInstance,isWatching){
            if (err) {
                console.log("watching the path " + watcherInstance.path + " failed with error", err);
            } else {
                console.log("watching the path " + watcherInstance.path + " completed");
            }
        },
        change: function(changeType,filePath,fileCurrentStat,filePreviousStat){
            console.log('a change event occured:',arguments);
        }
    },
    next: function(err,watchers){
        if (err) {
            return console.log("watching everything failed with error", err);
        } else {
            console.log('watching everything completed', watchers);
        }

        // Close watchers after 60 seconds
        setTimeout(function(){
            var i;
            console.log('Stop watching our paths');
            for ( i=0;  i<watchers.length; i++ ) {
                watchers[i].close();
            }
        },60*1000);
    }
});

You can test the above code snippet by running the following:

npm install -g watchr
watchr

History

Discover the change history by heading on over to the HISTORY.md file.

Contribute

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

Backers

Maintainers

These amazing people are maintaining this project:

Sponsors

No sponsors yet! Will you be the first?

Gittip donate button Flattr donate button PayPayl donate button BitCoin donate button Wishlist browse button

Contributors

These amazing people have contributed code to this project:

Become a contributor!

License

Licensed under the incredibly permissive MIT license

Copyright © 2012+ Bevry Pty Ltd us@bevry.me (http://bevry.me)
Copyright © 2011 Benjamin Lupton b@lupton.cc (http://balupton.com)

Something went wrong with that request. Please try again.