1 | # gaze [![Build Status](https://secure.travis-ci.org/shama/gaze.png?branch=master)](http://travis-ci.org/shama/gaze)
|
2 |
|
3 | A globbing fs.watch wrapper built from the best parts of other fine watch libs.
|
4 |
|
5 | Compatible with Node.js 0.10/0.8, Windows, OSX and Linux.
|
6 |
|
7 | ## Usage
|
8 | Install the module with: `npm install gaze` or place into your `package.json`
|
9 | and run `npm install`.
|
10 |
|
11 | ```javascript
|
12 | var gaze = require('gaze');
|
13 |
|
14 | // Watch all .js files/dirs in process.cwd()
|
15 | gaze('**/*.js', function(err, watcher) {
|
16 | // Files have all started watching
|
17 | // watcher === this
|
18 |
|
19 | // Get all watched files
|
20 | console.log(this.watched());
|
21 |
|
22 | // On file changed
|
23 | this.on('changed', function(filepath) {
|
24 | console.log(filepath + ' was changed');
|
25 | });
|
26 |
|
27 | // On file added
|
28 | this.on('added', function(filepath) {
|
29 | console.log(filepath + ' was added');
|
30 | });
|
31 |
|
32 | // On file deleted
|
33 | this.on('deleted', function(filepath) {
|
34 | console.log(filepath + ' was deleted');
|
35 | });
|
36 |
|
37 | // On changed/added/deleted
|
38 | this.on('all', function(event, filepath) {
|
39 | console.log(filepath + ' was ' + event);
|
40 | });
|
41 |
|
42 | // Get watched files with relative paths
|
43 | console.log(this.relative());
|
44 | });
|
45 |
|
46 | // Also accepts an array of patterns
|
47 | gaze(['stylesheets/*.css', 'images/**/*.png'], function() {
|
48 | // Add more patterns later to be watched
|
49 | this.add(['js/*.js']);
|
50 | });
|
51 | ```
|
52 |
|
53 | ### Alternate Interface
|
54 |
|
55 | ```javascript
|
56 | var Gaze = require('gaze').Gaze;
|
57 |
|
58 | var gaze = new Gaze('**/*');
|
59 |
|
60 | // Files have all started watching
|
61 | gaze.on('ready', function(watcher) { });
|
62 |
|
63 | // A file has been added/changed/deleted has occurred
|
64 | gaze.on('all', function(event, filepath) { });
|
65 | ```
|
66 |
|
67 | ### Errors
|
68 |
|
69 | ```javascript
|
70 | gaze('**/*', function() {
|
71 | this.on('error', function(err) {
|
72 | // Handle error here
|
73 | });
|
74 | });
|
75 | ```
|
76 |
|
77 | ### Minimatch / Glob
|
78 |
|
79 | See [isaacs's minimatch](https://github.com/isaacs/minimatch) for more
|
80 | information on glob patterns.
|
81 |
|
82 | ## Documentation
|
83 |
|
84 | ### gaze(patterns, [options], callback)
|
85 |
|
86 | * `patterns` {String|Array} File patterns to be matched
|
87 | * `options` {Object}
|
88 | * `callback` {Function}
|
89 | * `err` {Error | null}
|
90 | * `watcher` {Object} Instance of the Gaze watcher
|
91 |
|
92 | ### Class: gaze.Gaze
|
93 |
|
94 | Create a Gaze object by instanting the `gaze.Gaze` class.
|
95 |
|
96 | ```javascript
|
97 | var Gaze = require('gaze').Gaze;
|
98 | var gaze = new Gaze(pattern, options, callback);
|
99 | ```
|
100 |
|
101 | #### Properties
|
102 |
|
103 | * `options` The options object passed in.
|
104 | * `interval` {integer} Interval to pass to fs.watchFile
|
105 | * `debounceDelay` {integer} Delay for events called in succession for the same
|
106 | file/event
|
107 |
|
108 | #### Events
|
109 |
|
110 | * `ready(watcher)` When files have been globbed and watching has begun.
|
111 | * `all(event, filepath)` When an `added`, `changed` or `deleted` event occurs.
|
112 | * `added(filepath)` When a file has been added to a watch directory.
|
113 | * `changed(filepath)` When a file has been changed.
|
114 | * `deleted(filepath)` When a file has been deleted.
|
115 | * `renamed(newPath, oldPath)` When a file has been renamed.
|
116 | * `end()` When the watcher is closed and watches have been removed.
|
117 | * `error(err)` When an error occurs.
|
118 |
|
119 | #### Methods
|
120 |
|
121 | * `emit(event, [...])` Wrapper for the EventEmitter.emit.
|
122 | `added`|`changed`|`deleted` events will also trigger the `all` event.
|
123 | * `close()` Unwatch all files and reset the watch instance.
|
124 | * `add(patterns, callback)` Adds file(s) patterns to be watched.
|
125 | * `remove(filepath)` removes a file or directory from being watched. Does not
|
126 | recurse directories.
|
127 | * `watched()` Returns the currently watched files.
|
128 | * `relative([dir, unixify])` Returns the currently watched files with relative paths.
|
129 | * `dir` {string} Only return relative files for this directory.
|
130 | * `unixify` {boolean} Return paths with `/` instead of `\\` if on Windows.
|
131 |
|
132 | ## FAQs
|
133 |
|
134 | ### Why Another `fs.watch` Wrapper?
|
135 | I liked parts of other `fs.watch` wrappers but none had all the features I
|
136 | needed. This lib combines the features I needed from other fine watch libs:
|
137 | Speedy data behavior from
|
138 | [paulmillr's chokidar](https://github.com/paulmillr/chokidar), API interface
|
139 | from [mikeal's watch](https://github.com/mikeal/watch) and file globbing using
|
140 | [isaacs's glob](https://github.com/isaacs/node-glob) which is also used by
|
141 | [cowboy's Grunt](https://github.com/gruntjs/grunt).
|
142 |
|
143 | ### How do I fix the error `EMFILE: Too many opened files.`?
|
144 | This is because of your system's max opened file limit. For OSX the default is
|
145 | very low (256). Increase your limit temporarily with `ulimit -n 10480`, the
|
146 | number being the new max limit.
|
147 |
|
148 | ## Contributing
|
149 | In lieu of a formal styleguide, take care to maintain the existing coding style.
|
150 | Add unit tests for any new or changed functionality. Lint and test your code
|
151 | using [grunt](http://gruntjs.com/).
|
152 |
|
153 | ## Release History
|
154 | * 0.4.0 - Drop support for node v0.6. Use globule for file matching. Avoid node v0.10 path.resolve/join errors. Register new files when added to non-existent folder. Multiple instances can now poll the same files (@jpommerening).
|
155 | * 0.3.4 - Code clean up. Fix path must be strings errors (@groner). Fix incorrect added events (@groner).
|
156 | * 0.3.3 - Fix for multiple patterns with negate.
|
157 | * 0.3.2 - Emit `end` before removeAllListeners.
|
158 | * 0.3.1 - Fix added events within subfolder patterns.
|
159 | * 0.3.0 - Handle safewrite events, `forceWatchMethod` option removed, bug fixes and watch optimizations (@rgaskill).
|
160 | * 0.2.2 - Fix issue where subsequent add calls dont get watched (@samcday). removeAllListeners on close.
|
161 | * 0.2.1 - Fix issue with invalid `added` events in current working dir.
|
162 | * 0.2.0 - Support and mark folders with `path.sep`. Add `forceWatchMethod` option. Support `renamed` events.
|
163 | * 0.1.6 - Recognize the `cwd` option properly
|
164 | * 0.1.5 - Catch too many open file errors
|
165 | * 0.1.4 - Really fix the race condition with 2 watches
|
166 | * 0.1.3 - Fix race condition with 2 watches
|
167 | * 0.1.2 - Read triggering changed event fix
|
168 | * 0.1.1 - Minor fixes
|
169 | * 0.1.0 - Initial release
|
170 |
|
171 | ## License
|
172 | Copyright (c) 2013 Kyle Robinson Young
|
173 | Licensed under the MIT license.
|