basant307/AI_Governance_Project

1# Chokidar [![Weekly downloads](https://img.shields.io/npm/dw/chokidar.svg)](https://github.com/paulmillr/chokidar)2 3> Minimal and efficient cross-platform file watching library4 5## Why?6 7There are many reasons to prefer Chokidar to raw fs.watch / fs.watchFile in 2024:8 9- Events are properly reported10    - macOS events report filenames11    - events are not reported twice12    - changes are reported as add / change / unlink instead of useless `rename`13- Atomic writes are supported, using `atomic` option14    - Some file editors use them15- Chunked writes are supported, using `awaitWriteFinish` option16    - Large files are commonly written in chunks17- File / dir filtering is supported18- Symbolic links are supported19- Recursive watching is always supported, instead of partial when using raw events20    - Includes a way to limit recursion depth21 22Chokidar relies on the Node.js core `fs` module, but when using23`fs.watch` and `fs.watchFile` for watching, it normalizes the events it24receives, often checking for truth by getting file stats and/or dir contents.25The `fs.watch`-based implementation is the default, which26avoids polling and keeps CPU usage down. Be advised that chokidar will initiate27watchers recursively for everything within scope of the paths that have been28specified, so be judicious about not wasting system resources by watching much29more than needed. For some cases, `fs.watchFile`, which utilizes polling and uses more resources, is used.30 31Made for [Brunch](https://brunch.io/) in 2012,32it is now used in [~30 million repositories](https://www.npmjs.com/browse/depended/chokidar) and33has proven itself in production environments.34 35**Sep 2024 update:** v4 is out! It decreases dependency count from 13 to 1, removes36support for globs, adds support for ESM / Common.js modules, and bumps minimum node.js version from v8 to v14.37Check out [upgrading](#upgrading).38 39## Getting started40 41Install with npm:42 43```sh44npm install chokidar45```46 47Use it in your code:48 49```javascript50import chokidar from 'chokidar';51 52// One-liner for current directory53chokidar.watch('.').on('all', (event, path) => {54  console.log(event, path);55});56 57 58// Extended options59// ----------------60 61// Initialize watcher.62const watcher = chokidar.watch('file, dir, or array', {63  ignored: (path, stats) => stats?.isFile() && !path.endsWith('.js'), // only watch js files64  persistent: true65});66 67// Something to use when events are received.68const log = console.log.bind(console);69// Add event listeners.70watcher71  .on('add', path => log(`File ${path} has been added`))72  .on('change', path => log(`File ${path} has been changed`))73  .on('unlink', path => log(`File ${path} has been removed`));74 75// More possible events.76watcher77  .on('addDir', path => log(`Directory ${path} has been added`))78  .on('unlinkDir', path => log(`Directory ${path} has been removed`))79  .on('error', error => log(`Watcher error: ${error}`))80  .on('ready', () => log('Initial scan complete. Ready for changes'))81  .on('raw', (event, path, details) => { // internal82    log('Raw event info:', event, path, details);83  });84 85// 'add', 'addDir' and 'change' events also receive stat() results as second86// argument when available: https://nodejs.org/api/fs.html#fs_class_fs_stats87watcher.on('change', (path, stats) => {88  if (stats) console.log(`File ${path} changed size to ${stats.size}`);89});90 91// Watch new files.92watcher.add('new-file');93watcher.add(['new-file-2', 'new-file-3']);94 95// Get list of actual paths being watched on the filesystem96let watchedPaths = watcher.getWatched();97 98// Un-watch some files.99await watcher.unwatch('new-file');100 101// Stop watching. The method is async!102await watcher.close().then(() => console.log('closed'));103 104// Full list of options. See below for descriptions.105// Do not use this example!106chokidar.watch('file', {107  persistent: true,108 109  // ignore .txt files110  ignored: (file) => file.endsWith('.txt'),111  // watch only .txt files112  // ignored: (file, _stats) => _stats?.isFile() && !file.endsWith('.txt'),113 114  awaitWriteFinish: true, // emit single event when chunked writes are completed115  atomic: true, // emit proper events when "atomic writes" (mv _tmp file) are used116 117  // The options also allow specifying custom intervals in ms118  // awaitWriteFinish: {119  //   stabilityThreshold: 2000,120  //   pollInterval: 100121  // },122  // atomic: 100,123 124  interval: 100,125  binaryInterval: 300,126 127  cwd: '.',128  depth: 99,129 130  followSymlinks: true,131  ignoreInitial: false,132  ignorePermissionErrors: false,133  usePolling: false,134  alwaysStat: false,135});136 137```138 139`chokidar.watch(paths, [options])`140 141* `paths` (string or array of strings). Paths to files, dirs to be watched142recursively.143* `options` (object) Options object as defined below:144 145#### Persistence146 147* `persistent` (default: `true`). Indicates whether the process148should continue to run as long as files are being watched.149 150#### Path filtering151 152* `ignored` function, regex, or path. Defines files/paths to be ignored.153The whole relative or absolute path is tested, not just filename. If a function with two arguments154is provided, it gets called twice per path - once with a single argument (the path), second155time with two arguments (the path and the156[`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats)157object of that path).158* `ignoreInitial` (default: `false`). If set to `false` then `add`/`addDir` events are also emitted for matching paths while159instantiating the watching as chokidar discovers these file paths (before the `ready` event).160* `followSymlinks` (default: `true`). When `false`, only the161symlinks themselves will be watched for changes instead of following162the link references and bubbling events through the link's path.163* `cwd` (no default). The base directory from which watch `paths` are to be164derived. Paths emitted with events will be relative to this.165 166#### Performance167 168* `usePolling` (default: `false`).169Whether to use fs.watchFile (backed by polling), or fs.watch. If polling170leads to high CPU utilization, consider setting this to `false`. It is171typically necessary to **set this to `true` to successfully watch files over172a network**, and it may be necessary to successfully watch files in other173non-standard situations. Setting to `true` explicitly on MacOS overrides the174`useFsEvents` default. You may also set the CHOKIDAR_USEPOLLING env variable175to true (1) or false (0) in order to override this option.176* _Polling-specific settings_ (effective when `usePolling: true`)177  * `interval` (default: `100`). Interval of file system polling, in milliseconds. You may also178    set the CHOKIDAR_INTERVAL env variable to override this option.179  * `binaryInterval` (default: `300`). Interval of file system180  polling for binary files.181  ([see list of binary extensions](https://github.com/sindresorhus/binary-extensions/blob/master/binary-extensions.json))182* `alwaysStat` (default: `false`). If relying upon the183[`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats)184object that may get passed with `add`, `addDir`, and `change` events, set185this to `true` to ensure it is provided even in cases where it wasn't186already available from the underlying watch events.187* `depth` (default: `undefined`). If set, limits how many levels of188subdirectories will be traversed.189* `awaitWriteFinish` (default: `false`).190By default, the `add` event will fire when a file first appears on disk, before191the entire file has been written. Furthermore, in some cases some `change`192events will be emitted while the file is being written. In some cases,193especially when watching for large files there will be a need to wait for the194write operation to finish before responding to a file creation or modification.195Setting `awaitWriteFinish` to `true` (or a truthy value) will poll file size,196holding its `add` and `change` events until the size does not change for a197configurable amount of time. The appropriate duration setting is heavily198dependent on the OS and hardware. For accurate detection this parameter should199be relatively high, making file watching much less responsive.200Use with caution.201  * *`options.awaitWriteFinish` can be set to an object in order to adjust202  timing params:*203  * `awaitWriteFinish.stabilityThreshold` (default: 2000). Amount of time in204  milliseconds for a file size to remain constant before emitting its event.205  * `awaitWriteFinish.pollInterval` (default: 100). File size polling interval, in milliseconds.206 207#### Errors208 209* `ignorePermissionErrors` (default: `false`). Indicates whether to watch files210that don't have read permissions if possible. If watching fails due to `EPERM`211or `EACCES` with this set to `true`, the errors will be suppressed silently.212* `atomic` (default: `true` if `useFsEvents` and `usePolling` are `false`).213Automatically filters out artifacts that occur when using editors that use214"atomic writes" instead of writing directly to the source file. If a file is215re-added within 100 ms of being deleted, Chokidar emits a `change` event216rather than `unlink` then `add`. If the default of 100 ms does not work well217for you, you can override it by setting `atomic` to a custom value, in218milliseconds.219 220### Methods & Events221 222`chokidar.watch()` produces an instance of `FSWatcher`. Methods of `FSWatcher`:223 224* `.add(path / paths)`: Add files, directories for tracking.225Takes an array of strings or just one string.226* `.on(event, callback)`: Listen for an FS event.227Available events: `add`, `addDir`, `change`, `unlink`, `unlinkDir`, `ready`,228`raw`, `error`.229Additionally `all` is available which gets emitted with the underlying event230name and path for every event other than `ready`, `raw`, and `error`.  `raw` is internal, use it carefully.231* `.unwatch(path / paths)`: Stop watching files or directories.232Takes an array of strings or just one string.233* `.close()`: **async** Removes all listeners from watched files. Asynchronous, returns Promise. Use with `await` to ensure bugs don't happen.234* `.getWatched()`: Returns an object representing all the paths on the file235system being watched by this `FSWatcher` instance. The object's keys are all the236directories (using absolute paths unless the `cwd` option was used), and the237values are arrays of the names of the items contained in each directory.238 239### CLI240 241Check out third party [chokidar-cli](https://github.com/open-cli-tools/chokidar-cli),242which allows to execute a command on each change, or get a stdio stream of change events.243 244## Troubleshooting245 246Sometimes, Chokidar runs out of file handles, causing `EMFILE` and `ENOSP` errors:247 248* `bash: cannot set terminal process group (-1): Inappropriate ioctl for device bash: no job control in this shell`249* `Error: watch /home/ ENOSPC`250 251There are two things that can cause it.252 2531. Exhausted file handles for generic fs operations254    - Can be solved by using [graceful-fs](https://www.npmjs.com/package/graceful-fs),255      which can monkey-patch native `fs` module used by chokidar: `let fs = require('fs'); let grfs = require('graceful-fs'); grfs.gracefulify(fs);`256    - Can also be solved by tuning OS: `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`.2572. Exhausted file handles for `fs.watch`258    - Can't seem to be solved by graceful-fs or OS tuning259    - It's possible to start using `usePolling: true`, which will switch backend to resource-intensive `fs.watchFile`260 261All fsevents-related issues (`WARN optional dep failed`, `fsevents is not a constructor`) are solved by upgrading to v4+.262 263## Changelog264 265- **v4 (Sep 2024):** remove glob support and bundled fsevents. Decrease dependency count from 13 to 1. Rewrite in typescript. Bumps minimum node.js requirement to v14+266- **v3 (Apr 2019):** massive CPU & RAM consumption improvements; reduces deps / package size by a factor of 17x and bumps Node.js requirement to v8.16+.267- **v2 (Dec 2017):** globs are now posix-style-only. Tons of bugfixes.268- **v1 (Apr 2015):** glob support, symlink support, tons of bugfixes. Node 0.8+ is supported269- **v0.1 (Apr 2012):** Initial release, extracted from [Brunch](https://github.com/brunch/brunch/blob/9847a065aea300da99bd0753f90354cde9de1261/src/helpers.coffee#L66)270 271### Upgrading272 273If you've used globs before and want do replicate the functionality with v4:274 275```js276// v3277chok.watch('**/*.js');278chok.watch("./directory/**/*");279 280// v4281chok.watch('.', {282  ignored: (path, stats) => stats?.isFile() && !path.endsWith('.js'), // only watch js files283});284chok.watch('./directory');285 286// other way287import { glob } from 'node:fs/promises';288const watcher = watch(await Array.fromAsync(glob('**/*.js')));289 290// unwatching291// v3292chok.unwatch('**/*.js');293// v4294chok.unwatch(await glob('**/*.js'));295```296 297## Also298 299Why was chokidar named this way? What's the meaning behind it?300 301>Chowkidar is a transliteration of a Hindi word meaning 'watchman, gatekeeper', चौकीदार. This ultimately comes from Sanskrit _ चतुष्क_ (crossway, quadrangle, consisting-of-four). This word is also used in other languages like Urdu as (چوکیدار) which is widely used in Pakistan and India. 302 303## License304 305MIT (c) Paul Miller (<https://paulmillr.com>), see [LICENSE](LICENSE) file.306