sane
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
- Uses
fs.watchby default and sensibly works around the various issues - Maintains a consistent API across different platforms
- Where
fs.watchis not reliable you have the choice of using the following alternatives:
Install
$ npm install sane
How to choose a mode
Don't worry too much about choosing the correct mode upfront because sane maintains the same API across all modes and will be easy to switch.
- If you're only supporting Linux and OS X,
watchmanwould 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 into nodejs/node-v0.x-archive#5463, use
watchman - 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
API
sane(dir, options)
Watches a directory and all its descendant directories for changes, deletions, and additions on files and directories.
var watcher = 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); });
// close
watcher.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 use watchman.watchmanPath: sets a custom path forwatchmanbinary.watchexec: makes the watcher use watchexec.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, see micromatch.
If you choose to use watchman you'll have to install watchman yourself).
If you choose to use watchexec you'll have to install watchexec yourself).
For the ignored options, see anymatch.
sane.NodeWatcher(dir, options)
The default watcher class. Uses fs.watch under the hood, and takes the same options as sane(dir, options).
sane.WatchmanWatcher(dir, options)
The watchman watcher class. Takes the same options as sane(dir, options).
sane.Watchexec(dir, options)
The watchexec watcher class. Takes the same options as sane(dir, options).
sane.PollWatcher(dir, options)
The polling watcher class. Takes the same options as sane(dir, options) with the addition of:
- interval: indicates how often the files should be polled. (passed to fs.watchFile)
sane.{Node|Watchman|Watchexec|Poll}Watcher#close
Stops watching.
sane.{Node|Watchman|Watchexec|Poll}Watcher events
Emits the following events:
All events are passed the file/dir path relative to the root directory
readywhen the program is ready to detect events in the directorychangewhen a file changesaddwhen a file or directory has been addeddeletewhen a file or directory has been deleted
CLI
This module includes a simple command line interface, which you can install with npm 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 given directory and run the given every time a file changes.
CLI example usage
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=3sane 'echo "A command ran"' -p
License
MIT
Credits
The CLI was originally based on the watch CLI. Watch is licensed under the Apache License Version 2.0.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent