| 1 |
# watch -- Utilities for watching file trees in node.js |
| 2 |
|
| 3 |
## Install |
| 4 |
|
| 5 |
<pre> |
| 6 |
npm install watch |
| 7 |
</pre> |
| 8 |
|
| 9 |
## Purpose |
| 10 |
|
| 11 |
The intention of this module is provide tools that make managing the watching of file & directory trees easier. |
| 12 |
|
| 13 |
#### watch.watchTree(root, [options,] callback) |
| 14 |
|
| 15 |
The first argument is the directory root you want to watch. |
| 16 |
|
| 17 |
The options object is passed to fs.watchFile but can also be used to provide two additional watchTree specific options: |
| 18 |
|
| 19 |
* `'ignoreDotFiles'` - When true this option means that when the file tree is walked it will ignore files that being with "." |
| 20 |
* `'filter'` - You can use this option to provide a function that returns true or false for each file and directory to decide whether or not that file/directory is included in the watcher. |
| 21 |
* `'interval'` - Specifies the interval duration in seconds, the time period between polling for file changes. |
| 22 |
* `'ignoreUnreadableDir'` - When true, this options means that when a file can't be read, this file is silently skipped. |
| 23 |
* `'ignoreNotPermitted'` - When true, this options means that when a file can't be read due to permission issues, this file is silently skipped. |
| 24 |
* `'ignoreDirectoryPattern'` - When a regex pattern is set, e.g. /node_modules/, these directories are silently skipped. |
| 25 |
|
| 26 |
The callback takes 3 arguments. The first is the file that was modified. The second is the current stat object for that file and the third is the previous stat object. |
| 27 |
|
| 28 |
When a file is new the previous stat object is null. |
| 29 |
|
| 30 |
When watchTree is finished walking the tree and adding all the listeners it passes the file hash (keys are the file/directory names and the values are the current stat objects) as the first argument and null as both the previous and current stat object arguments. |
| 31 |
|
| 32 |
<pre> |
| 33 |
watch.watchTree('/home/mikeal', function (f, curr, prev) { |
| 34 |
if (typeof f == "object" && prev === null && curr === null) { |
| 35 |
// Finished walking the tree |
| 36 |
} else if (prev === null) { |
| 37 |
// f is a new file |
| 38 |
} else if (curr.nlink === 0) { |
| 39 |
// f was removed |
| 40 |
} else { |
| 41 |
// f was changed |
| 42 |
} |
| 43 |
}) |
| 44 |
</pre> |
| 45 |
|
| 46 |
### watch.unwatchTree(root) |
| 47 |
|
| 48 |
Unwatch a previously watched directory root using `watch.watchTree`. |
| 49 |
|
| 50 |
### watch.createMonitor(root, [options,] callback) |
| 51 |
|
| 52 |
This function creates an EventEmitter that gives notifications for different changes that happen to the file and directory tree under the given root argument. |
| 53 |
|
| 54 |
The options object is passed to watch.watchTree. |
| 55 |
|
| 56 |
The callback receives the monitor object. |
| 57 |
|
| 58 |
The monitor object contains a property, `files`, which is a hash of files and directories as keys with the current stat object as the value. |
| 59 |
|
| 60 |
The monitor has the following events. |
| 61 |
|
| 62 |
* `'created'` - New file has been created. Two arguments, the filename and the stat object. |
| 63 |
* `'removed'` - A file has been moved or deleted. Two arguments, the filename and the stat object for the fd. |
| 64 |
* `'changed'` - A file has been changed. Three arguments, the filename, the current stat object, and the previous stat object. |
| 65 |
|
| 66 |
The monitor can be stopped using `.stop` (calls `unwatchTree`). |
| 67 |
|
| 68 |
<pre> |
| 69 |
var watch = require('watch') |
| 70 |
watch.createMonitor('/home/mikeal', function (monitor) { |
| 71 |
monitor.files['/home/mikeal/.zshrc'] // Stat object for my zshrc. |
| 72 |
monitor.on("created", function (f, stat) { |
| 73 |
// Handle new files |
| 74 |
}) |
| 75 |
monitor.on("changed", function (f, curr, prev) { |
| 76 |
// Handle file changes |
| 77 |
}) |
| 78 |
monitor.on("removed", function (f, stat) { |
| 79 |
// Handle removed files |
| 80 |
}) |
| 81 |
monitor.stop(); // Stop watching |
| 82 |
}) |
| 83 |
</pre> |
| 84 |
|
| 85 |
### CLI |
| 86 |
|
| 87 |
This module includes a simple command line interface, which you can install with `npm install watch -g`. |
| 88 |
|
| 89 |
|
| 90 |
``` |
| 91 |
Usage: watch <command> [...directory] [OPTIONS] |
| 92 |
|
| 93 |
OPTIONS: |
| 94 |
--wait=<seconds> |
| 95 |
Duration, in seconds, that watching will be disabled |
| 96 |
after running <command>. Setting this option will |
| 97 |
throttle calls to <command> for the specified duration. |
| 98 |
|
| 99 |
--filter=<file> |
| 100 |
Path to a require-able .js file that exports a filter |
| 101 |
function to be passed to watchTreeOptions.filter. |
| 102 |
Path is resolved relative to process.cwd(). |
| 103 |
|
| 104 |
--interval=<seconds> |
| 105 |
Specifies the interval duration in seconds, the time period between polling for file changes. |
| 106 |
|
| 107 |
--ignoreDotFiles, -d |
| 108 |
Ignores dot or hidden files in the watch [directory]. |
| 109 |
|
| 110 |
--ignoreUnreadable, -u |
| 111 |
Silently ignores files that cannot be read within the |
| 112 |
watch [directory]. |
| 113 |
|
| 114 |
--ignoreDirectoryPattern=<regexp>, -p |
| 115 |
Silently skips directories that match the regular |
| 116 |
expression. |
| 117 |
``` |
| 118 |
|
| 119 |
It will watch the given directories (defaults to the current working directory) with `watchTree` and run the given command every time a file changes. |
| 120 |
|
| 121 |
### Examples |
| 122 |
|
| 123 |
As stated above the pattern is: |
| 124 |
|
| 125 |
watch <command> [...directory] [OPTIONS] |
| 126 |
|
| 127 |
To run the watch command in the terminal you have to write the following: |
| 128 |
|
| 129 |
watch 'npm run test -s' directory |
| 130 |
|
| 131 |
As the command has to be written in quotation marks Windows users may need to use double quotes rather than single quotes |
| 132 |
|
| 133 |
watch "npm run test -s" directory |
| 134 |
|
| 135 |
Note: Because Windows users may need to use double quotes rather than single quotes they need to escape the them in npm scripts |
| 136 |
|
| 137 |
"scripts": { |
| 138 |
"watch:osx": "watch 'npm run test -s' source" |
| 139 |
"watch:windows": "watch \"npm run test -s\" source", |
| 140 |
} |
| 141 |
|
| 142 |
|
| 143 |
## Contributing |
| 144 |
|
| 145 |
### Releasing |
| 146 |
|
| 147 |
On the latest clean `master`: |
| 148 |
|
| 149 |
``` |
| 150 |
npm run release:major |
| 151 |
npm run release:minor |
| 152 |
npm run release:patch |
| 153 |
``` |