watch

What is watch?

The 'watch' npm package is a utility that allows you to monitor files and directories for changes. It can be used to trigger actions when files are modified, added, or deleted, making it useful for tasks such as automated testing, live reloading, and continuous integration.

What are watch's main functionalities?

Watch a single file

This feature allows you to watch a single file for changes. When the file is modified, the callback function is triggered.

const watch = require('watch');

watch.watchFile('/path/to/file', function (curr, prev) {
  console.log('File changed');
});

Watch a directory

This feature allows you to watch a directory and its subdirectories for changes. The callback function is triggered when files are added, removed, or modified.

const watch = require('watch');

watch.watchTree('/path/to/dir', function (f, curr, prev) {
  if (typeof f == 'object' && prev === null && curr === null) {
    console.log('Finished walking the tree');
  } else if (prev === null) {
    console.log('New file added: ' + f);
  } else if (curr.nlink === 0) {
    console.log('File removed: ' + f);
  } else {
    console.log('File changed: ' + f);
  }
});

Ignore specific files or directories

This feature allows you to ignore specific files or directories while watching. In this example, dot files and the 'node_modules' directory are ignored.

const watch = require('watch');

watch.watchTree('/path/to/dir', {
  ignoreDotFiles: true,
  filter: function (f, stat) {
    return !/node_modules/.test(f);
  }
}, function (f, curr, prev) {
  console.log('File changed: ' + f);
});

Other packages similar to watch

chokidar

Chokidar is a highly efficient and feature-rich file watcher. It uses native OS events to provide fast and reliable file watching. Compared to 'watch', Chokidar offers more advanced features such as debouncing, polling, and support for various file system events.

gaze

Gaze is another file watcher that provides a simple API for watching files and directories. It supports recursive watching and can be used as a drop-in replacement for 'watch'. Gaze is known for its ease of use and flexibility.

node-watch

Node-watch is a lightweight file watcher that provides a simple API for watching files and directories. It is similar to 'watch' but offers better performance and reliability. Node-watch is suitable for projects that require minimal dependencies and fast file watching.

README

watch -- Utilities for watching file trees in node.js

Install

  npm install watch

Purpose

The intention of this module is provide tools that make managing the watching of file & directory trees easier.

watch.watchTree(root, [options,] callback)

The first argument is the directory root you want to watch.

The options object is passed to fs.watchFile but can also be used to provide two additional watchTree specific options:

• 'ignoreDotFiles' - When true this option means that when the file tree is walked it will ignore files that being with "."
• '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.
• 'interval' - Specifies the interval duration in seconds, the time period between polling for file changes.
• 'ignoreUnreadableDir' - When true, this options means that when a file can't be read, this file is silently skipped.
• 'ignoreNotPermitted' - When true, this options means that when a file can't be read due to permission issues, this file is silently skipped.
• 'ignoreDirectoryPattern' - When a regex pattern is set, e.g. /node_modules/, these directories are silently skipped.

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.

When a file is new the previous stat object is null.

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.

  watch.watchTree('/home/mikeal', function (f, curr, prev) {
    if (typeof f == "object" && prev === null && curr === null) {
      // Finished walking the tree
    } else if (prev === null) {
      // f is a new file
    } else if (curr.nlink === 0) {
      // f was removed
    } else {
      // f was changed
    }
  })

watch.unwatchTree(root)

Unwatch a previously watched directory root using watch.watchTree.

watch.createMonitor(root, [options,] callback)

This function creates an EventEmitter that gives notifications for different changes that happen to the file and directory tree under the given root argument.

The options object is passed to watch.watchTree.

The callback receives the monitor object.

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.

The monitor has the following events.

• 'created' - New file has been created. Two arguments, the filename and the stat object.
• 'removed' - A file has been moved or deleted. Two arguments, the filename and the stat object for the fd.
• 'changed' - A file has been changed. Three arguments, the filename, the current stat object, and the previous stat object.

The monitor can be stopped using .stop (calls unwatchTree).

  var watch = require('watch')
  watch.createMonitor('/home/mikeal', function (monitor) {
    monitor.files['/home/mikeal/.zshrc'] // Stat object for my zshrc.
    monitor.on("created", function (f, stat) {
      // Handle new files
    })
    monitor.on("changed", function (f, curr, prev) {
      // Handle file changes
    })
    monitor.on("removed", function (f, stat) {
      // Handle removed files
    })
    monitor.stop(); // Stop watching
  })

CLI

This module includes a simple command line interface, which you can install with npm install watch -g.

Usage: watch <command> [...directory] [OPTIONS]

OPTIONS:
    --wait=<seconds>
        Duration, in seconds, that watching will be disabled
        after running <command>. Setting this option will
        throttle calls to <command> for the specified duration.

    --filter=<file>
        Path to a require-able .js file that exports a filter
        function to be passed to watchTreeOptions.filter.
        Path is resolved relative to process.cwd().

    --interval=<seconds>
        Specifies the interval duration in seconds, the time period between polling for file changes.

    --ignoreDotFiles, -d
        Ignores dot or hidden files in the watch [directory].

     --ignoreUnreadable, -u
        Silently ignores files that cannot be read within the
        watch [directory].

     --ignoreDirectoryPattern=<regexp>, -p
        Silently skips directories that match the regular
        expression.

It will watch the given directories (defaults to the current working directory) with watchTree and run the given command every time a file changes.

Contributing

Releasing

On the latest clean master:

npm run release:major
npm run release:minor
npm run release:patch