watch a set of files for changes (including create/delete) by glob patterns
Globwatcher is a node library that monitors a filesystem for changes to files
specified by glob patterns, and triggers events when a file is added, changed,
or deleted. It's built on top of node's
fs.watch mechanism, and uses the
glob pattern syntax of the
var globwatcher = globwatcher;var watcher = ;watcher;watcherready;
Create a new
GlobWatcher object, which will monitor for files that match
the given patterns (or a single pattern), and trigger events. The
object can contain:
cwd - folder to use for relative patterns. If not given, the process's
current working directory is used. Absolute patterns (patterns that start
with "/") don't use this option.
interval - frequency (in milliseconds) to monitor existing files for
changes. Default is 250, or 1/4 second.
debounceInterval - delay (in milliseconds) to wait after receiving a
"folder has changed" notification before scanning the folder. This helps
alleviate thundering-herd problems where many files may be created or
deleted in a short period. Default is 10 milliseconds.
emitFolders - if true, emit
deleted signals for folders
too. Folder filenames will always end in "/".
snapshot - previous state to resume from, as captured with
(see "Snapshots" below).
persistent - if false, unref the watches so they don't keep node running.
Default is false.
debug - a function to call to log debug info while running. This function
will be called with a string to log whenever certain changes or events
occur, so it can be noisy, but may be useful for general debugging.
ready - a promise that will be fulfilled once all the watches have been
created and the initial scan is complete. This can be used to run code that
depends on globwatcher being active.
originalPatterns - the original (non-normalized) patterns used to create
this globwatcher, including any added with
add(patterns...) - Add new glob patterns to be scanned. This will reset
ready promise (described above) so that it's fulfilled only when this
new set of patterns are active.
close() - Stop monitoring and free all resources. No new events will be
sent after this call returns, and all "watch" resources will be freed.
stopWatches() - Stop monitoring temporarily. Pending events may still
arrive after this call returns, but no new events will be triggered, and
all "watch" resources will be freed. The watched patterns will be
remembered, so you can call
startWatches() again to resume monitoring.
startWatches() - Resume monitoring after a
stopWatches() call. You
don't need to call this function when first monitoring -- it's called by
the constructor automatically.
check() - Immediately scan interesting folders and files and trigger
events on changes. You don't need to call this function normally, but if
you believe files have changed, and want to bypass the normal scan
interval, this call may speed up the latency between a filesystem event and
the event signalled by globwatcher. Returns a promise that is fulfilled
when the check is finished.
currentSet() - Return the set of filenames that currently exist and match
the glob pattern being scanned. The filenames are all absolute.
snapshot() - Return an object representing the current state of watched
folders and files. (See "Snapshots" below.)
added(filename) - a new file that matches one of the watched patterns was
deleted(filename) - a file that matches one of the watched patterns was
changed(filename) - a file that matches one of the watched patterns was
changed, either by modification time or size
The filename argument to events is always an absolute filename.
FileWatcher class is a pure-js replacement for the
interface, with an extra
check method. It's primarily an implementation
detail of globwatcher, but feel free to use it directly.
A FileWatcher calls
fs.stat on a set of files, on a recurring timer. If
any of the files has a changed modification time or size, a "changed" event
is signalled. File creation/deletion is ignored.
options object can contain:
period - the period of the timer. Default is 250, or 1/4 second.
persistent - if false, unref the timer so that it doesn't keep node
running. Default is true.
close() - Stop the timer and clear the list of filenames being watched.
watch(filename) - Add this filename to the list being watched, if it
isn't already there. Returns the watch object for this filename.
unwatch(filename) - Remove this filename from the list being watched, if
watchFor(filename) - Return the watch object for a filename, if it's
in the list of filenames benig watched. If not, return undefined.
check() - Immediately scan every filename currently being watched, and
trigger events on changes. This has the same purpose as the "check"
function on globwatcher.
The "watch" object returned by
watchFor has one function and
check() - Immediately scan this filename for changes.
changed - the event signalled when a file has changed
node (as of v0.10) provides two ways to "watch" files/folders for changes:
fs.watchFile, which calls
fs.staton the file at regular intervals
fs.watch, which tries to take advantage of OS-level file watching system calls
Of the two,
watch seems most obviously the best, but is the least portable.
Linux has the best support with inotify, but OS X still uses kqueue, and can
only notify when the contents of a folder have changed. Nested sub-folders
aren't monitored either.
So globwatch uses the minimatch library to parse the globs, and sets OS-level folder watches on any interesting folders that exist. If a named folder doesn't exist, it walks up the tree until it finds one that does exist, and watches that, looking for the subtree to be created.
OS-level watches are only placed on folders, since they're the only ones
guaranteed to work, and they only trigger a re-scan of the folder contents.
Any matching filenames are watched with file-level watches, which are
The current state of a globwatcher can be captured with
returns an object containing metadata about files that currently match. This
lets you "resume" a session later, potentially in a new process or at a much
To resume watching, pass the snapshot object as a
snapshot option into a
var watcher = ;var snapshot = watcher;// ... time passes ...val newWatcher = ;
When restoring from a snapshot, globwatcher will wait for the debounce interval to pass, then scan the filesystem and trigger events for any files that have changed since the snapshot. (Naturally, this may have odd results if your match patterns have changed.)
On OS X, the modification time ("mtime") of files is only stored to the nearest second, so if a file is modified twice in one second, and stays the same size, globwatch won't notice the second change. I can't think of a way to work around this -- it's a limitation of the filesystem -- but I'm open to suggestions.
The timer for file-level scanning determines how rapidly the "change" event
will trigger. At the default timer interval of 1/4 second, at the worst case,
it may be 1/4 second between a file modification and the "change" event
triggering. If you've performed operations that might have caused files to
change, you can alleviate this somewhat by calling
check() to cause an
Apache 2 (open-source) license, included in 'LICENSE.txt'.
@robey - Robey Pointer firstname.lastname@example.org