# fsmonitor

> Fine-grained cross-platform file system monitoring for Node.js

Latest version **0.2.4** (published 2014-08-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install fsmonitor
pnpm add fsmonitor
yarn add fsmonitor
bun add fsmonitor
```

Provides the command `fsmonitor`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.4 |
| Published | 2014-08-20 |
| First published | 2012-10-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 49 |
| Author | Andrey Tarantsov |
| Maintainers | andreyvit, nitoyon |
| Keywords | fs, file, watch, watcher, monitor, change |

## Links

- npm: https://www.npmjs.com/package/fsmonitor
- Repository: https://github.com/andreyvit/fsmonitor.js
- Issues: https://github.com/andreyvit/fsmonitor.js/issues
- npm.io page: https://npm.io/package/fsmonitor

## Dependencies (2)

- [debug](https://npm.io/package/debug.md) ~0.7.0
- [pathspec](https://npm.io/package/pathspec.md) ~0.9.2

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 0.2.4 (latest) — 2014-08-20
- 0.2.2 — 2013-03-19
- 0.2.1 — 2013-02-24
- 0.2.0 — 2012-11-05
- 0.1.2 — 2012-10-31
- 0.1.1 — 2012-10-16
- 0.1.0 — 2012-10-16

## README

# File-grained cross-platform FS monitoring for Node.js

**Wait, wait, how's it different from `fs.watch`?** Unlike `fs.watch`, fsmonitor:

* monitors an entire subtree (`fs.watch` only monitors a single folder)
* gives you the entire list of added, removed and modified files and folders (e.g. when you add or delete a non-empty folder, the change event will contain a list of all files in that folder)

Here's what happens when you call `fsmonitor.watch(path)`:

* The specified file system subtree is scanned, and the stat data is kept in memory.
* `fs.watch` is called to start monitoring every subfolder encountered.
* When change events are reported, the subtree is rescanned to determine the list of changes.
* `fs.watch` is called for the new subfolders, and the watchers are shut down for the removed ones.


## Status

Alpha stage. Seems to work, waiting for feedback, shipping as part of LiveReload 0.5 for Windows.

Planned features:

* only reporting changes in the files matching .gitignore-style masks you specify (using pathspec module for handling masks)
* more efficient native code implementations on Mac and Windows
* offloading per-folder monitoring backends to child processes to avoid hitting the limit on the number of file handles


## Installation

    npm install fsmonitor

or, to use fsmonitor command-line tool (see below):

    npm install -g fsmonitor


## Usage

    fsmonitor = require('fsmonitor');
    fsmonitor.watch('/some/folder', null, function(change) {
        console.log("Change detected:\n" + change);  # has a nice toString

        console.log("Added files:    %j", change.addedFiles);
        console.log("Modified files: %j", change.modifiedFiles);
        console.log("Removed files:  %j", change.removedFiles);

        console.log("Added folders:    %j", change.addedFolders);
        console.log("Modified folders: %j", change.modifiedFolders);
        console.log("Removed folders:  %j", change.removedFolders);
    });

    var monitor = fsmonitor.watch('.', {
        // include files
        matches: function(relpath) {
            return relpath.match(/\.js$/i) !== null;
        },
        // exclude directories
        excludes: function(relpath) {
            return relpath.match(/^\.git$/i) !== null;
        }
    });
    monitor.on('change', function(changes) {
        console.log(changes);
    });


## Command-line tool

Includes a command-line tool that can report changes and/or run a specified command on every change.

For example, to invoke `npm test` when any JavaScript file is modified:

    fsmonitor -s -p '+*.js' npm test

Usage:

    Usage: fsmonitor [-d <folder>] [-p] [-s] [-q] [<mask>]... [<command> <arg>...]

    Options:
      -d <folder>        Specify the folder to monitor (defaults to the current folder)
      -p                 Print changes to console (default if no command specified)
      -s                 Run the provided command once on start up
      -q                 Quiet mode (don't print the initial banner)

    Masks:
      +<mask>            Include only the files matching the given mask
      !<mask>            Exclude files matching the given mask

      If no inclusion masks are provided, all files not explicitly excluded will be included.

    General options:
      --help             Display this message
      --version          Display fsmonitor version number


## Unit test

Install necessary modules:

    npm install

Start `npm test` to run the unit tests:

    npm test

---
_Source: https://npm.io/package/fsmonitor · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
