1 | [![Try on repl.it](https://repl-badge.jajoosam.repl.co/try.png)](https://repl.it/@amasad/sane-playground)
|
2 | ![CI](https://github.com/amasad/sane/workflows/CI/badge.svg)
|
3 |
|
4 | sane
|
5 | ----
|
6 |
|
7 | I've been driven to insanity by node filesystem watcher wrappers.
|
8 | Sane aims to be fast, small, and reliable file system watcher. It does that by:
|
9 |
|
10 | * By default stays away from fs polling because it's very slow and cpu intensive
|
11 | * Uses `fs.watch` by default and sensibly works around the various issues
|
12 | * Maintains a consistent API across different platforms
|
13 | * Where `fs.watch` is not reliable you have the choice of using the following alternatives:
|
14 | * [the facebook watchman library](https://facebook.github.io/watchman/)
|
15 | * [the watchexec library](https://github.com/watchexec/watchexec)
|
16 | * polling
|
17 |
|
18 | ## Install
|
19 |
|
20 | ```
|
21 | $ npm install sane
|
22 | ```
|
23 |
|
24 | ## How to choose a mode
|
25 |
|
26 | Don't worry too much about choosing the correct mode upfront because sane
|
27 | maintains the same API across all modes and will be easy to switch.
|
28 |
|
29 | * If you're only supporting Linux and OS X, `watchman` would be the most reliable mode
|
30 | * If you're using node > v0.10.0 use the default mode
|
31 | * 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`
|
32 | * If you're in an environment where native file system events aren't available (like Vagrant), you should use polling
|
33 | * Otherwise, the default mode should work well for you
|
34 |
|
35 | ## API
|
36 |
|
37 | ### sane(dir, options)
|
38 |
|
39 | Watches a directory and all its descendant directories for changes, deletions, and additions on files and directories.
|
40 |
|
41 | ```js
|
42 | var watcher = sane('path/to/dir', {glob: ['**/*.js', '**/*.css']});
|
43 | watcher.on('ready', function () { console.log('ready') });
|
44 | watcher.on('change', function (filepath, root, stat) { console.log('file changed', filepath); });
|
45 | watcher.on('add', function (filepath, root, stat) { console.log('file added', filepath); });
|
46 | watcher.on('delete', function (filepath, root) { console.log('file deleted', filepath); });
|
47 | // close
|
48 | watcher.close();
|
49 | ```
|
50 |
|
51 | options:
|
52 |
|
53 | * `glob`: a single string glob pattern or an array of them.
|
54 | * `poll`: puts the watcher in polling mode. Under the hood that means `fs.watchFile`.
|
55 | * `watchman`: makes the watcher use [watchman](https://facebook.github.io/watchman/).
|
56 | * `watchmanPath`: sets a custom path for `watchman` binary.
|
57 | * `watchexec`: makes the watcher use [watchexec](https://github.com/watchexec/watchexec).
|
58 | * `dot`: enables watching files/directories that start with a dot.
|
59 | * `ignored`: a glob, regex, function, or array of any combination.
|
60 |
|
61 | For the glob pattern documentation, see [micromatch](https://github.com/micromatch/micromatch).
|
62 | If you choose to use `watchman` you'll have to [install watchman yourself](https://facebook.github.io/watchman/docs/install.html)).
|
63 | If you choose to use `watchexec` you'll have to [install watchexec yourself](https://github.com/watchexec/watchexec)).
|
64 | For the ignored options, see [anymatch](https://github.com/es128/anymatch).
|
65 |
|
66 | ### sane.NodeWatcher(dir, options)
|
67 |
|
68 | The default watcher class. Uses `fs.watch` under the hood, and takes the same options as `sane(dir, options)`.
|
69 |
|
70 | ### sane.WatchmanWatcher(dir, options)
|
71 |
|
72 | The watchman watcher class. Takes the same options as `sane(dir, options)`.
|
73 |
|
74 | ### sane.Watchexec(dir, options)
|
75 |
|
76 | The watchexec watcher class. Takes the same options as `sane(dir, options)`.
|
77 |
|
78 | ### sane.PollWatcher(dir, options)
|
79 |
|
80 | The polling watcher class. Takes the same options as `sane(dir, options)` with the addition of:
|
81 |
|
82 | * interval: indicates how often the files should be polled. (passed to fs.watchFile)
|
83 |
|
84 | ### sane.{Node|Watchman|Watchexec|Poll}Watcher#close
|
85 |
|
86 | Stops watching.
|
87 |
|
88 | ### sane.{Node|Watchman|Watchexec|Poll}Watcher events
|
89 |
|
90 | Emits the following events:
|
91 |
|
92 | All events are passed the file/dir path relative to the root directory
|
93 | * `ready` when the program is ready to detect events in the directory
|
94 | * `change` when a file changes
|
95 | * `add` when a file or directory has been added
|
96 | * `delete` when a file or directory has been deleted
|
97 |
|
98 | ## CLI
|
99 |
|
100 | This module includes a simple command line interface, which you can install with `npm install sane -g`.
|
101 |
|
102 | ```
|
103 | Usage: sane <command> [...directory] [--glob=<filePattern>] [--poll] [--watchman] [--watchman-path=<watchmanBinaryPath>] [--dot] [--wait=<seconds>]
|
104 |
|
105 | OPTIONS:
|
106 | --glob=<filePattern>
|
107 | A single string glob pattern or an array of them.
|
108 |
|
109 | --ignored=<filePattern>
|
110 | A glob, regex, function, or array of any combination.
|
111 |
|
112 | --poll, -p
|
113 | Use polling mode.
|
114 |
|
115 | --watchman, -w
|
116 | Use watchman (if available).
|
117 |
|
118 | --watchman-path=<watchmanBinaryPath>
|
119 | Sets a custom path for watchman binary (if using this mode).
|
120 |
|
121 | --dot, -d
|
122 | Enables watching files/directories that start with a dot.
|
123 |
|
124 | --wait=<seconds>
|
125 | Duration, in seconds, that watching will be disabled
|
126 | after running <command>. Setting this option will
|
127 | throttle calls to <command> for the specified duration.
|
128 | --quiet, -q
|
129 | Disables sane's console output
|
130 |
|
131 | --changes-only, -o
|
132 | Runs <command> only when a change occur. Skips running <command> at startup
|
133 | ```
|
134 |
|
135 | It will watch the given `directory` and run the given <command> every time a file changes.
|
136 |
|
137 | ### CLI example usage
|
138 | - `sane 'echo "A command ran"'`
|
139 | - `sane 'echo "A command ran"' --glob='**/*.css'`
|
140 | - `sane 'echo "A command ran"' site/assets/css --glob='**/*.css'`
|
141 | - `sane 'echo "A command ran"' --glob='**/*.css' --ignored='**/ignore.css'`
|
142 | - `sane 'echo "A command ran"' --wait=3`
|
143 | - `sane 'echo "A command ran"' -p`
|
144 |
|
145 | ## License
|
146 |
|
147 | MIT
|
148 |
|
149 | ## Credits
|
150 | The CLI was originally based on the [watch CLI](https://github.com/mikeal/watch). Watch is licensed under the Apache License Version 2.0.
|