1 | # gaze [![Build Status](http://img.shields.io/travis/shama/gaze.svg)](https://travis-ci.org/shama/gaze) [![Build status](https://ci.appveyor.com/api/projects/status/vtx65w9eg511tgo4)](https://ci.appveyor.com/project/shama/gaze)
|
2 |
|
3 | A globbing `fs.watch` wrapper built from the best parts of other fine watch libs.
|
4 | Compatible with Node.js >= 4.x, Windows, macOS, and Linux.
|
5 |
|
6 | ![gaze](http://dontkry.com/images/repos/gaze.png)
|
7 |
|
8 | [![NPM](https://nodei.co/npm/gaze.png?downloads=true)](https://nodei.co/npm/gaze/)
|
9 |
|
10 | ## Usage
|
11 | Install the module with: `npm install gaze` or place into your `package.json`
|
12 | and run `npm install`.
|
13 |
|
14 | ```javascript
|
15 | var gaze = require('gaze');
|
16 |
|
17 | // Watch all .js files/dirs in process.cwd()
|
18 | gaze('**/*.js', function(err, watcher) {
|
19 | // Files have all started watching
|
20 | // watcher === this
|
21 |
|
22 | // Get all watched files
|
23 | var watched = this.watched();
|
24 |
|
25 | // On file changed
|
26 | this.on('changed', function(filepath) {
|
27 | console.log(filepath + ' was changed');
|
28 | });
|
29 |
|
30 | // On file added
|
31 | this.on('added', function(filepath) {
|
32 | console.log(filepath + ' was added');
|
33 | });
|
34 |
|
35 | // On file deleted
|
36 | this.on('deleted', function(filepath) {
|
37 | console.log(filepath + ' was deleted');
|
38 | });
|
39 |
|
40 | // On changed/added/deleted
|
41 | this.on('all', function(event, filepath) {
|
42 | console.log(filepath + ' was ' + event);
|
43 | });
|
44 |
|
45 | // Get watched files with relative paths
|
46 | var files = this.relative();
|
47 | });
|
48 |
|
49 | // Also accepts an array of patterns
|
50 | gaze(['stylesheets/*.css', 'images/**/*.png'], function() {
|
51 | // Add more patterns later to be watched
|
52 | this.add(['js/*.js']);
|
53 | });
|
54 | ```
|
55 |
|
56 | ### Alternate Interface
|
57 |
|
58 | ```javascript
|
59 | var Gaze = require('gaze').Gaze;
|
60 |
|
61 | var gaze = new Gaze('**/*');
|
62 |
|
63 | // Files have all started watching
|
64 | gaze.on('ready', function(watcher) { });
|
65 |
|
66 | // A file has been added/changed/deleted has occurred
|
67 | gaze.on('all', function(event, filepath) { });
|
68 | ```
|
69 |
|
70 | ### Errors
|
71 |
|
72 | ```javascript
|
73 | gaze('**/*', function(error, watcher) {
|
74 | if (error) {
|
75 | // Handle error if it occurred while starting up
|
76 | }
|
77 | });
|
78 |
|
79 | // Or with the alternative interface
|
80 | var gaze = new Gaze();
|
81 | gaze.on('error', function(error) {
|
82 | // Handle error here
|
83 | });
|
84 | gaze.add('**/*');
|
85 | ```
|
86 |
|
87 | ### Minimatch / Glob
|
88 |
|
89 | See [isaacs's `minimatch`](https://github.com/isaacs/minimatch) for more
|
90 | information on glob patterns.
|
91 |
|
92 | ## Documentation
|
93 |
|
94 | ### gaze([patterns, options, callback])
|
95 |
|
96 | * `patterns` {`String`|`Array`} File patterns to be matched
|
97 | * `options` {`Object`}
|
98 | * `callback` {`Function`}
|
99 | * `err` {`Error` | `null`}
|
100 | * `watcher` {`Object`} Instance of the `Gaze` watcher
|
101 |
|
102 | ### Class: `gaze.Gaze`
|
103 |
|
104 | Create a `Gaze` object by instancing the `gaze.Gaze` class.
|
105 |
|
106 | ```javascript
|
107 | var Gaze = require('gaze').Gaze;
|
108 | var gaze = new Gaze(pattern, options, callback);
|
109 | ```
|
110 |
|
111 | #### Properties
|
112 |
|
113 | * `options` The options object passed in.
|
114 | * `interval` {integer} Interval to pass to `fs.watchFile`
|
115 | * `debounceDelay` {integer} Delay for events called in succession for the same
|
116 | file/event in milliseconds
|
117 | * `mode` {string} Force the watch mode. Either `'auto'` (default), `'watch'` (force native events), or `'poll'` (force stat polling).
|
118 | * `cwd` {string} The current working directory to base file patterns from. Default is `process.cwd()`.
|
119 |
|
120 | #### Events
|
121 |
|
122 | * `ready(watcher)` When files have been globbed and watching has begun.
|
123 | * `all(event, filepath)` When an `added`, `changed`, `renamed`, or `deleted` event occurs.
|
124 | * `added(filepath)` When a file has been added to a watch directory.
|
125 | * `changed(filepath)` When a file has been changed.
|
126 | * `deleted(filepath)` When a file has been deleted.
|
127 | * `renamed(newPath, oldPath)` When a file has been renamed.
|
128 | * `end()` When the watcher is closed and watches have been removed.
|
129 | * `error(err)` When an error occurs.
|
130 | * `nomatch` When no files have been matched.
|
131 |
|
132 | #### Methods
|
133 |
|
134 | * `emit(event, [...])` Wrapper for `EventEmitter.emit`.
|
135 | `added`|`changed`|`renamed`|`deleted` events will also trigger the `all` event.
|
136 | * `close()` Unwatch all files and reset the watch instance.
|
137 | * `add(patterns, callback)` Adds file(s) `patterns` to be watched.
|
138 | * `remove(filepath)` Removes a file or directory from being watched. Does not
|
139 | recurse directories.
|
140 | * `watched()` Returns the currently watched files.
|
141 | * `relative([dir, unixify])` Returns the currently watched files with relative paths.
|
142 | * `dir` {string} Only return relative files for this directory.
|
143 | * `unixify` {boolean} Return paths with `/` instead of `\\` if on Windows.
|
144 |
|
145 | ## Similar Projects
|
146 |
|
147 | Other great watch libraries to try are:
|
148 |
|
149 | * [paulmillr's `chokidar`](https://github.com/paulmillr/chokidar)
|
150 | * [amasad's `sane`](https://github.com/amasad/sane)
|
151 | * [mikeal's `watch`](https://github.com/mikeal/watch)
|
152 | * [github's `pathwatcher`](https://github.com/atom/node-pathwatcher)
|
153 | * [bevry's `watchr`](https://github.com/bevry/watchr)
|
154 |
|
155 | ## Contributing
|
156 | In lieu of a formal styleguide, take care to maintain the existing coding style.
|
157 | Add unit tests for any new or changed functionality. Lint and test your code
|
158 | using [grunt](http://gruntjs.com/).
|
159 |
|
160 | ## Release History
|
161 | * 1.1.3 - Fix for Node 10 support (@aredridel). Officially dropping support for Node < 4.
|
162 | * 1.1.2 - Prevent more `ENOENT` errors from escaping (@alexgorbatchev).
|
163 | * 1.1.1 - Prevent `fs.watch` errors from escaping error handler (@rosen-vladimirov). Fix `_addToWatched` without `path.sep` (@wyicwx).
|
164 | * 1.1.0 - Update to `globule@1.0.0` with `minimatch >= 3.0.0`.
|
165 | * 1.0.0 - Revert back to 0.5.2. Drop support for Node.js v0.8. Fix for `maxListeners`. Update `globule` to `0.2.0`.
|
166 | * 0.6.4 - Catch and emit `error` from `readdir` (@oconnore). Fix for `0 maxListeners`. Use `graceful-fs` to avoid `EMFILE` errors in other places `fs` is used. Better method to determine if `pathwatcher` was built. Fix keeping process alive too much, only init `pathwatcher` if a file is being watched. Set min required to Windows Vista when building on Windows (@pvolok).
|
167 | * 0.6.3 - Add support for Node.js v0.11
|
168 | * 0.6.2 - Fix argument error with `watched()`. Fix for erroneous `added` events on folders. Ignore `msvs` build error 4244.
|
169 | * 0.6.1 - Fix for absolute paths.
|
170 | * 0.6.0 - Uses native OS events (fork of `pathwatcher`) but can fall back to stat polling. Everything is async to avoid blocking, including `relative()` and `watched()`. Better error handling. Update to `globule@0.2.0`. No longer watches `cwd` by default. Added `mode` option. Better `EMFILE` message. Avoids `ENOENT` errors with symlinks. All constructor arguments are optional.
|
171 | * 0.5.2 - Fix for `ENOENT` error with non-existent symlinks [BACKPORTED].
|
172 | * 0.5.1 - Use `setImmediate` (`process.nextTick` for Node.js v0.8) to defer `ready`/`nomatch` events (@amasad).
|
173 | * 0.5.0 - Process is now kept alive while watching files. Emits a `nomatch` event when no files are matching.
|
174 | * 0.4.3 - Track file additions in newly created folders (@brett-shwom).
|
175 | * 0.4.2 - Fix `.remove()` method to remove a single file in a directory (@kaelzhang). Fixing “`Cannot call method 'call' of undefined`” (@krasimir). Track new file additions within folders (@brett-shwom).
|
176 | * 0.4.1 - Fix `watchDir` not respecting close in race condition (@chrisirhc).
|
177 | * 0.4.0 - Drop support for Node.js v0.6. Use `globule` for file matching. Avoid Node.js v0.10 `path.resolve`/`join` errors. Register new files when added to non-existent folder. Multiple instances can now poll the same files (@jpommerening).
|
178 | * 0.3.4 - Code clean up. Fix “`path must be strings`” errors (@groner). Fix incorrect `added` events (@groner).
|
179 | * 0.3.3 - Fix for multiple patterns with negate.
|
180 | * 0.3.2 - Emit `end` before `removeAllListeners`.
|
181 | * 0.3.1 - Fix `added` events within subfolder patterns.
|
182 | * 0.3.0 - Handle safewrite events, `forceWatchMethod` option removed, bug fixes and watch optimizations (@rgaskill).
|
183 | * 0.2.2 - Fix issue where subsequent `add` calls dont get watched (@samcday). `removeAllListeners` on `close`.
|
184 | * 0.2.1 - Fix issue with invalid `added` events in current working dir.
|
185 | * 0.2.0 - Support and mark folders with `path.sep`. Add `forceWatchMethod` option. Support `renamed` events.
|
186 | * 0.1.6 - Recognize the `cwd` option properly
|
187 | * 0.1.5 - Catch “`too many open file`” errors
|
188 | * 0.1.4 - Really fix the race condition with 2 watches
|
189 | * 0.1.3 - Fix race condition with 2 watches
|
190 | * 0.1.2 - Read triggering changed event fix
|
191 | * 0.1.1 - Minor fixes
|
192 | * 0.1.0 - Initial release
|
193 |
|
194 | ## License
|
195 | Copyright (c) 2018 Kyle Robinson Young
|
196 | Licensed under the MIT license.
|