Repository files navigation

I've been driven to insanity by node filesystem watcher wrappers.Sane aims to be fast, small, and reliable file system watcher. It does that by:

• By default stays away from fs polling because it's very slow and cpu intensive
• Usesfs.watch by default and sensibly works around the various issues
• Maintains a consistent API across different platforms
• Wherefs.watch is not reliable you have the choice of using the following alternatives:
  • the facebook watchman library
  • the watchexec library
  • polling

$ npm install sane

Don't worry too much about choosing the correct mode upfront because sanemaintains the same API across all modes and will be easy to switch.

• If you're only supporting Linux and OS X,watchman would be the most reliable mode
• If you're using node > v0.10.0 use the default mode
• If you're running OS X and you're watching a lot of directories and you're running intonodejs/node-v0.x-archive#5463, usewatchman
• If you're in an environment where native file system events aren't available (like Vagrant), you should use polling
• Otherwise, the default mode should work well for you

Watches a directory and all its descendant directories for changes, deletions, and additions on files and directories.

varwatcher=sane('path/to/dir',{glob:['**/*.js','**/*.css']});watcher.on('ready',function(){console.log('ready')});watcher.on('change',function(filepath,root,stat){console.log('file changed',filepath);});watcher.on('add',function(filepath,root,stat){console.log('file added',filepath);});watcher.on('delete',function(filepath,root){console.log('file deleted',filepath);});// closewatcher.close();

options:

• glob: a single string glob pattern or an array of them.
• poll: puts the watcher in polling mode. Under the hood that meansfs.watchFile.
• watchman: makes the watcher usewatchman.
• watchmanPath: sets a custom path forwatchman binary.
• watchexec: makes the watcher usewatchexec.
• dot: enables watching files/directories that start with a dot.
• ignored: a glob, regex, function, or array of any combination.

For the glob pattern documentation, seemicromatch.If you choose to usewatchman you'll have toinstall watchman yourself).If you choose to usewatchexec you'll have toinstall watchexec yourself).For the ignored options, seeanymatch.

The default watcher class. Usesfs.watch under the hood, and takes the same options assane(dir, options).

The watchman watcher class. Takes the same options assane(dir, options).

The watchexec watcher class. Takes the same options assane(dir, options).

The polling watcher class. Takes the same options assane(dir, options) with the addition of:

• interval: indicates how often the files should be polled. (passed to fs.watchFile)

Stops watching.

Emits the following events:

All events are passed the file/dir path relative to the root directory

• ready when the program is ready to detect events in the directory
• change when a file changes
• add when a file or directory has been added
• delete when a file or directory has been deleted

This module includes a simple command line interface, which you can install withnpm install sane -g.

Usage: sane <command> [...directory] [--glob=<filePattern>] [--poll] [--watchman] [--watchman-path=<watchmanBinaryPath>] [--dot] [--wait=<seconds>]OPTIONS:    --glob=<filePattern>      A single string glob pattern or an array of them.    --ignored=<filePattern>      A glob, regex, function, or array of any combination.    --poll, -p      Use polling mode.    --watchman, -w      Use watchman (if available).    --watchman-path=<watchmanBinaryPath>      Sets a custom path for watchman binary (if using this mode).    --dot, -d      Enables watching files/directories that start with a dot.    --wait=<seconds>      Duration, in seconds, that watching will be disabled      after running <command>. Setting this option will      throttle calls to <command> for the specified duration.    --quiet, -q      Disables sane's console output    --changes-only, -o      Runs <command> only when a change occur. Skips running <command> at startup

It will watch the givendirectory and run the given every time a file changes.

• sane 'echo "A command ran"'
• sane 'echo "A command ran"' --glob='**/*.css'
• sane 'echo "A command ran"' site/assets/css --glob='**/*.css'
• sane 'echo "A command ran"' --glob='**/*.css' --ignored='**/ignore.css'
• sane 'echo "A command ran"' --wait=3
• sane 'echo "A command ran"' -p

MIT

The CLI was originally based on thewatch CLI. Watch is licensed under the Apache License Version 2.0.