# sane > Sane aims to be fast, small, and reliable file system watcher. Latest version **5.0.1** (published 2021-06-28) · MIT license · 0 weekly downloads ## Install ```sh npm install sane pnpm add sane yarn add sane bun add sane ``` Provides the command `sane`. ## Health **Score 23/100 (F)** — status: abandoned. Positive: has types package; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 5.0.1 | | Published | 2021-06-28 | | First published | 2014-02-25 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | separate (@types/sane) | | Module format | CommonJS | | Node | 10.* \|\| >= 12.* | | Dependencies | 9 | | Unpacked size | 49.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 387 | | Author | amasad | | Maintainers | amasad, stefanpenner, coscholl | | Keywords | watch, file, fswatcher, watchfile, fs, watching | ## Links - npm: https://www.npmjs.com/package/sane - Repository: https://github.com/amasad/sane - Issues: https://github.com/amasad/sane/issues - npm.io page: https://npm.io/package/sane ## Dependencies (9) - [execa](https://npm.io/package/execa.md) ^4.0.0 - [walker](https://npm.io/package/walker.md) ~1.0.5 - [exec-sh](https://npm.io/package/exec-sh.md) ^0.3.4 - [anymatch](https://npm.io/package/anymatch.md) ^3.1.1 - [minimist](https://npm.io/package/minimist.md) ^1.1.1 - [micromatch](https://npm.io/package/micromatch.md) ^4.0.2 - [fb-watchman](https://npm.io/package/fb-watchman.md) ^2.0.1 - [capture-exit](https://npm.io/package/capture-exit.md) ^2.0.0 - [@cnakazawa/watch](https://npm.io/package/@cnakazawa/watch.md) ^1.0.3 ## Alternatives - [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads - [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads - [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads - [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads - [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads ## Recent versions - 5.0.1 (latest) — 2021-06-28 - 5.0.0 — 2021-06-28 - 4.1.0 — 2019-03-15 - 4.0.3 — 2019-03-03 - 4.0.2 — 2018-11-02 - 4.0.1 — 2018-09-27 - 4.0.0 — 2018-09-26 - 3.1.0 — 2018-09-26 - 3.0.0 — 2018-07-31 - 2.5.2 — 2018-05-07 - 2.5.1 — 2018-05-04 - 2.5.0 — 2018-03-16 - 2.4.1 — 2018-02-08 - 2.4.0 — 2018-02-08 - 2.3.0 — 2018-01-22 - … 43 more at https://npm.io/package/sane/versions ## README [![Try on repl.it](https://repl-badge.jajoosam.repl.co/try.png)](https://repl.it/@amasad/sane-playground) ![CI](https://github.com/amasad/sane/workflows/CI/badge.svg) 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.watch` by default and sensibly works around the various issues * Maintains a consistent API across different platforms * Where `fs.watch` is not reliable you have the choice of using the following alternatives: * [the facebook watchman library](https://facebook.github.io/watchman/) * [the watchexec library](https://github.com/watchexec/watchexec) * polling ## 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, `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 into https://github.com/joyent/node/issues/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. ```js 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 means `fs.watchFile`. * `watchman`: makes the watcher use [watchman](https://facebook.github.io/watchman/). * `watchmanPath`: sets a custom path for `watchman` binary. * `watchexec`: makes the watcher use [watchexec](https://github.com/watchexec/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](https://github.com/micromatch/micromatch). If you choose to use `watchman` you'll have to [install watchman yourself](https://facebook.github.io/watchman/docs/install.html)). If you choose to use `watchexec` you'll have to [install watchexec yourself](https://github.com/watchexec/watchexec)). For the ignored options, see [anymatch](https://github.com/es128/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 * `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 ## CLI This module includes a simple command line interface, which you can install with `npm install sane -g`. ``` Usage: sane [...directory] [--glob=] [--poll] [--watchman] [--watchman-path=] [--dot] [--wait=] OPTIONS: --glob= A single string glob pattern or an array of them. --ignored= A glob, regex, function, or array of any combination. --poll, -p Use polling mode. --watchman, -w Use watchman (if available). --watchman-path= Sets a custom path for watchman binary (if using this mode). --dot, -d Enables watching files/directories that start with a dot. --wait= Duration, in seconds, that watching will be disabled after running . Setting this option will throttle calls to for the specified duration. --quiet, -q Disables sane's console output --changes-only, -o Runs only when a change occur. Skips running 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=3` - `sane 'echo "A command ran"' -p` ## License MIT ## Credits The CLI was originally based on the [watch CLI](https://github.com/mikeal/watch). Watch is licensed under the Apache License Version 2.0. --- _Source: https://npm.io/package/sane · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._