{"id":16953142,"url":"https://github.com/c4milo/node-inotify","last_synced_at":"2025-04-04T17:06:50.588Z","repository":{"id":973084,"uuid":"770551","full_name":"c4milo/node-inotify","owner":"c4milo","description":"Inotify bindings for Node.JS","archived":false,"fork":false,"pushed_at":"2020-10-02T22:13:40.000Z","size":555,"stargazers_count":243,"open_issues_count":7,"forks_count":39,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-10-20T23:45:54.199Z","etag":null,"topics":["inotify","linux","node-inotify","nodejs","watch"],"latest_commit_sha":null,"homepage":"http://c4milo.github.io/node-inotify","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/c4milo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-07-12T15:09:52.000Z","updated_at":"2024-02-26T11:14:18.000Z","dependencies_parsed_at":"2022-07-05T22:30:19.928Z","dependency_job_id":null,"html_url":"https://github.com/c4milo/node-inotify","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c4milo%2Fnode-inotify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c4milo%2Fnode-inotify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c4milo%2Fnode-inotify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c4milo%2Fnode-inotify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/c4milo","download_url":"https://codeload.github.com/c4milo/node-inotify/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217177,"owners_count":20903009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["inotify","linux","node-inotify","nodejs","watch"],"created_at":"2024-10-13T22:06:24.847Z","updated_at":"2025-04-04T17:06:50.566Z","avatar_url":"https://github.com/c4milo.png","language":"C++","readme":"# node-inotify - monitoring file system events in GNU/Linux with [NodeJS][nodejs_home]\n[![Build Status](https://travis-ci.org/c4milo/node-inotify.svg?branch=master)](https://travis-ci.org/c4milo/node-inotify)\n\nThe inotify API provides a mechanism for monitoring file system events.\nInotify can be used to monitor individual files, or to monitor directories.\nWhen a directory is monitored, inotify will return events for the directory\nitself, and for files inside the directory. [(ref: GNU/Linux Manual)][inotify.7]\n\n## Installation\n[NodeJS][nodejs_dev] versions 4.x.x up to 11.x.x are currently supported and tested.\n\n### Install from NPM\n\n```shell\n    $ npm install inotify\n```\n\n### Install from git\n\n```shell\n$ npm install node-gyp -g\n$ git clone git://github.com/c4milo/node-inotify.git\n$ cd node-inotify\n$ node-gyp rebuild\n```\n\n## API\n  * `var inotify = new Inotify()`: Creates a new instance of Inotify. By default it's in persistent mode.\n  You can specify `false` in `var inotify = new Inotify(false)` to use the non persistent mode.\n\n  * `var wd = inotify.addWatch(arg)`:  Adds a watch for files or directories. This will then return a watch descriptor. The argument is an object as follows\n```javascript\n    var arg = {\n        // Path to be monitored.\n        path: '.',\n        // An optional OR'ed set of events to watch for.\n        // If they're not specified, it will use\n        // Inotify.IN_ALL_EVENTS by default.\n        watch_for: Inotify.IN_ALL_EVENTS,\n        // Callback function that will receive each event.\n        callback: function (event) {}\n    }\n```\nYou can call this function as many times as you want in order to monitor different paths.\n**Monitoring of directories is not recursive**: to monitor subdirectories under a directory, additional *watches* must be created.\n\n  * `inotify.removeWatch(watch_descriptor)`: Remove a watch associated with the watch_descriptor param and returns `true` if the action was successful or `false` in the opposite case. Removing a watch causes an `Inotify.IN_IGNORED` event to be generated for this watch descriptor.\n\n  * `inotify.close()`: Remove all the watches and close the inotify's file descriptor. Returns `true` if the action was successful or false in the opposite case.\n\n### Event object structure\n```javascript\nvar event = {\n    watch: Watch descriptor,\n    mask: Mask of events,\n    cookie: Cookie that permits to associate events,\n    name: Optional name of the object being watched\n};\n```\n\nThe `event.name` property is only present when an event is returned for a file inside a watched directory; it identifies the file path name relative to the watched directory.\n\n\n## Example of use\n\n```javascript\n    var Inotify = require('inotify').Inotify;\n    var inotify = new Inotify(); //persistent by default, new Inotify(false) //no persistent\n\n    var data = {}; //used to correlate two events\n\n    var callback = function(event) {\n        var mask = event.mask;\n        var type = mask \u0026 Inotify.IN_ISDIR ? 'directory ' : 'file ';\n        if (event.name) {\n            type += ' ' + event.name + ' ';\n        } else {\n            type += ' ';\n        }\n        // the purpose of this hell of 'if' statements is only illustrative.\n\n        if (mask \u0026 Inotify.IN_ACCESS) {\n            console.log(type + 'was accessed ');\n        } else if (mask \u0026 Inotify.IN_MODIFY) {\n            console.log(type + 'was modified ');\n        } else if (mask \u0026 Inotify.IN_OPEN) {\n            console.log(type + 'was opened ');\n        } else if (mask \u0026 Inotify.IN_CLOSE_NOWRITE) {\n            console.log(type + ' opened for reading was closed ');\n        } else if (mask \u0026 Inotify.IN_CLOSE_WRITE) {\n            console.log(type + ' opened for writing was closed ');\n        } else if (mask \u0026 Inotify.IN_ATTRIB) {\n            console.log(type + 'metadata changed ');\n        } else if (mask \u0026 Inotify.IN_CREATE) {\n            console.log(type + 'created');\n        } else if (mask \u0026 Inotify.IN_DELETE) {\n            console.log(type + 'deleted');\n        } else if (mask \u0026 Inotify.IN_DELETE_SELF) {\n            console.log(type + 'watched deleted ');\n        } else if (mask \u0026 Inotify.IN_MOVE_SELF) {\n            console.log(type + 'watched moved');\n        } else if (mask \u0026 Inotify.IN_IGNORED) {\n            console.log(type + 'watch was removed');\n        } else if (mask \u0026 Inotify.IN_MOVED_FROM) {\n            data = event;\n            data.type = type;\n        } else if (mask \u0026 Inotify.IN_MOVED_TO) {\n            if ( Object.keys(data).length \u0026\u0026\n                data.cookie === event.cookie) {\n                console.log(type + ' moved to ' + data.type);\n                data = {};\n            }\n        }\n    }\n    var home_dir = {\n        // Change this for a valid directory in your machine.\n        path:      '/home/camilo',\n        watch_for: Inotify.IN_OPEN | Inotify.IN_CLOSE,\n        callback:  callback\n    };\n\n    var home_watch_descriptor = inotify.addWatch(home_dir);\n\n    var home2_dir = {\n        // Change this for a valid directory in your machine\n        path:      '/home/bob',\n        watch_for: Inotify.IN_ALL_EVENTS,\n        callback:  callback\n    };\n\n    var home2_wd = inotify.addWatch(home2_dir);\n\n```\n\n## Inotify Events\n\n### Watch for:\n * **Inotify.IN_ACCESS:** File was accessed (read)\n * **Inotify.IN_ATTRIB:** Metadata changed, e.g., permissions, timestamps, extended attributes, link count (since Linux 2.6.25), UID, GID, etc.\n * **Inotify.IN_CLOSE_WRITE:** File opened for writing was closed\n * **Inotify.IN_CLOSE_NOWRITE:** File not opened for writing was closed\n * **Inotify.IN_CREATE:** File/directory created in the watched directory\n * **Inotify.IN_DELETE:** File/directory deleted from the watched directory\n * **Inotify.IN_DELETE_SELF:** Watched file/directory was deleted\n * **Inotify.IN_MODIFY:** File was modified\n * **Inotify.IN_MOVE_SELF:** Watched file/directory was moved\n * **Inotify.IN_MOVED_FROM:** File moved out of the watched directory\n * **Inotify.IN_MOVED_TO:** File moved into watched directory\n * **Inotify.IN_OPEN:** File was opened\n * **Inotify.IN_ALL_EVENTS:** Watch for all kind of events\n * **Inotify.IN_CLOSE:**  (IN_CLOSE_WRITE | IN_CLOSE_NOWRITE)  Close\n * **Inotify.IN_MOVE:**  (IN_MOVED_FROM | IN_MOVED_TO)  Moves\n\n### Additional Flags:\n * **Inotify.IN_ONLYDIR:** Only watch the path if it is a directory.\n * **Inotify.IN_DONT_FOLLOW:** Do not follow symbolics links\n * **Inotify.IN_ONESHOT:** Only send events once\n * **Inotify.IN_MASK_ADD:** Add (OR) events to watch mask for this pathname if it already exists (instead of replacing the mask).\n\n### The following bits may be set in the `event.mask` property returned in the callback\n * **Inotify.IN_IGNORED:** Watch was removed explicitly with inotify.removeWatch(watch_descriptor) or automatically (the file was deleted, or the file system was unmounted)\n * **Inotify.IN_ISDIR:** Subject of this event is a directory\n * **Inotify.IN_Q_OVERFLOW:** Event queue overflowed (wd is -1 for this event)\n * **Inotify.IN_UNMOUNT:** File system containing the watched object was unmounted\n\n\n## FAQ\n### Why inotify does not watch directories recursively?\nhttp://www.quora.com/Inotify-monitoring-of-directories-is-not-recursive-Is-there-any-specific-reason-for-this-design-in-Linux-kernel\n\n\n## License\n(The MIT License)\n\nCopyright 2019 node-inotify AUTHORS. All rights reserved.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to\ndeal in the Software without restriction, including without limitation the\nrights to use, copy, modify, merge, publish, distribute, sublicense, and/or\nsell copies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\nFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\nIN THE SOFTWARE.\n\n\n[inotify.7]: http://www.kernel.org/doc/man-pages/online/pages/man7/inotify.7.html \"http://www.kernel.org/doc/man-pages/online/pages/man7/inotify.7.html\"\n[nodejs_home]: http://www.nodejs.org\n[nodejs_dev]: http://github.com/joyent/node\n[code_example]: http://gist.github.com/476119\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc4milo%2Fnode-inotify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fc4milo%2Fnode-inotify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc4milo%2Fnode-inotify/lists"}