{"id":13416711,"url":"https://github.com/fsnotify/fsnotify","last_synced_at":"2025-05-12T18:05:55.738Z","repository":{"id":18188971,"uuid":"21306961","full_name":"fsnotify/fsnotify","owner":"fsnotify","description":"Cross-platform filesystem notifications for Go.","archived":false,"fork":false,"pushed_at":"2025-04-23T19:51:39.000Z","size":877,"stargazers_count":10053,"open_issues_count":29,"forks_count":941,"subscribers_count":150,"default_branch":"main","last_synced_at":"2025-05-05T15:19:52.906Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fsnotify.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"arp242"}},"created_at":"2014-06-28T16:47:01.000Z","updated_at":"2025-05-04T16:47:21.000Z","dependencies_parsed_at":"2023-12-07T10:34:14.096Z","dependency_job_id":"0d26be37-27af-457c-a464-6cdfa08a5aa5","html_url":"https://github.com/fsnotify/fsnotify","commit_stats":{"total_commits":554,"total_committers":76,"mean_commits":"7.2894736842105265","dds":0.703971119133574,"last_synced_commit":"a9bc2e01792f868516acf80817f7d7d7b3315409"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsnotify%2Ffsnotify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsnotify%2Ffsnotify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsnotify%2Ffsnotify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsnotify%2Ffsnotify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fsnotify","download_url":"https://codeload.github.com/fsnotify/fsnotify/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252522178,"owners_count":21761685,"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":[],"created_at":"2024-07-30T22:00:20.656Z","updated_at":"2025-05-05T15:20:15.018Z","avatar_url":"https://github.com/fsnotify.png","language":"Go","funding_links":["https://github.com/sponsors/arp242"],"categories":["Popular","Go","HarmonyOS","开源类库","File System","Misc","Programming","Open source library","语言资源库","Repositories","Golang"],"sub_categories":["Windows Manager","文件/存储","Golang","Files/Storage","go","Utils"],"readme":"fsnotify is a Go library to provide cross-platform filesystem notifications on\nWindows, Linux, macOS, BSD, and illumos.\n\nGo 1.17 or newer is required; the full documentation is at\nhttps://pkg.go.dev/github.com/fsnotify/fsnotify\n\n---\n\nPlatform support:\n\n| Backend               | OS         | Status                                                                    |\n| :-------------------- | :--------- | :------------------------------------------------------------------------ |\n| inotify               | Linux      | Supported                                                                 |\n| kqueue                | BSD, macOS | Supported                                                                 |\n| ReadDirectoryChangesW | Windows    | Supported                                                                 |\n| FEN                   | illumos    | Supported                                                                 |\n| fanotify              | Linux 5.9+ | [Not yet](https://github.com/fsnotify/fsnotify/issues/114)                |\n| FSEvents              | macOS      | [Needs support in x/sys/unix][fsevents]                                   |\n| USN Journals          | Windows    | [Needs support in x/sys/windows][usn]                                     |\n| Polling               | *All*      | [Not yet](https://github.com/fsnotify/fsnotify/issues/9)                  |\n\nLinux and illumos should include Android and Solaris, but these are currently\nuntested.\n\n[fsevents]:   https://github.com/fsnotify/fsnotify/issues/11#issuecomment-1279133120\n[usn]:        https://github.com/fsnotify/fsnotify/issues/53#issuecomment-1279829847\n\nUsage\n-----\nA basic example:\n\n```go\npackage main\n\nimport (\n    \"log\"\n\n    \"github.com/fsnotify/fsnotify\"\n)\n\nfunc main() {\n    // Create new watcher.\n    watcher, err := fsnotify.NewWatcher()\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer watcher.Close()\n\n    // Start listening for events.\n    go func() {\n        for {\n            select {\n            case event, ok := \u003c-watcher.Events:\n                if !ok {\n                    return\n                }\n                log.Println(\"event:\", event)\n                if event.Has(fsnotify.Write) {\n                    log.Println(\"modified file:\", event.Name)\n                }\n            case err, ok := \u003c-watcher.Errors:\n                if !ok {\n                    return\n                }\n                log.Println(\"error:\", err)\n            }\n        }\n    }()\n\n    // Add a path.\n    err = watcher.Add(\"/tmp\")\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    // Block main goroutine forever.\n    \u003c-make(chan struct{})\n}\n```\n\nSome more examples can be found in [cmd/fsnotify](cmd/fsnotify), which can be\nrun with:\n\n    % go run ./cmd/fsnotify\n\nFurther detailed documentation can be found in godoc:\nhttps://pkg.go.dev/github.com/fsnotify/fsnotify\n\nFAQ\n---\n### Will a file still be watched when it's moved to another directory?\nNo, not unless you are watching the location it was moved to.\n\n### Are subdirectories watched?\nNo, you must add watches for any directory you want to watch (a recursive\nwatcher is on the roadmap: [#18]).\n\n[#18]: https://github.com/fsnotify/fsnotify/issues/18\n\n### Do I have to watch the Error and Event channels in a goroutine?\nYes. You can read both channels in the same goroutine using `select` (you don't\nneed a separate goroutine for both channels; see the example).\n\n### Why don't notifications work with NFS, SMB, FUSE, /proc, or /sys?\nfsnotify requires support from underlying OS to work. The current NFS and SMB\nprotocols does not provide network level support for file notifications, and\nneither do the /proc and /sys virtual filesystems.\n\nThis could be fixed with a polling watcher ([#9]), but it's not yet implemented.\n\n[#9]: https://github.com/fsnotify/fsnotify/issues/9\n\n### Why do I get many Chmod events?\nSome programs may generate a lot of attribute changes; for example Spotlight on\nmacOS, anti-virus programs, backup applications, and some others are known to do\nthis. As a rule, it's typically best to ignore Chmod events. They're often not\nuseful, and tend to cause problems.\n\nSpotlight indexing on macOS can result in multiple events (see [#15]). A\ntemporary workaround is to add your folder(s) to the *Spotlight Privacy\nsettings* until we have a native FSEvents implementation (see [#11]).\n\n[#11]: https://github.com/fsnotify/fsnotify/issues/11\n[#15]: https://github.com/fsnotify/fsnotify/issues/15\n\n### Watching a file doesn't work well\nWatching individual files (rather than directories) is generally not recommended\nas many programs (especially editors) update files atomically: it will write to\na temporary file which is then moved to to destination, overwriting the original\n(or some variant thereof). The watcher on the original file is now lost, as that\nno longer exists.\n\nThe upshot of this is that a power failure or crash won't leave a half-written\nfile.\n\nWatch the parent directory and use `Event.Name` to filter out files you're not\ninterested in. There is an example of this in `cmd/fsnotify/file.go`.\n\nPlatform-specific notes\n-----------------------\n### Linux\nWhen a file is removed a REMOVE event won't be emitted until all file\ndescriptors are closed; it will emit a CHMOD instead:\n\n    fp := os.Open(\"file\")\n    os.Remove(\"file\")        // CHMOD\n    fp.Close()               // REMOVE\n\nThis is the event that inotify sends, so not much can be changed about this.\n\nThe `fs.inotify.max_user_watches` sysctl variable specifies the upper limit for\nthe number of watches per user, and `fs.inotify.max_user_instances` specifies\nthe maximum number of inotify instances per user. Every Watcher you create is an\n\"instance\", and every path you add is a \"watch\".\n\nThese are also exposed in `/proc` as `/proc/sys/fs/inotify/max_user_watches` and\n`/proc/sys/fs/inotify/max_user_instances`\n\nTo increase them you can use `sysctl` or write the value to proc file:\n\n    # The default values on Linux 5.18\n    sysctl fs.inotify.max_user_watches=124983\n    sysctl fs.inotify.max_user_instances=128\n\nTo make the changes persist on reboot edit `/etc/sysctl.conf` or\n`/usr/lib/sysctl.d/50-default.conf` (details differ per Linux distro; check your\ndistro's documentation):\n\n    fs.inotify.max_user_watches=124983\n    fs.inotify.max_user_instances=128\n\nReaching the limit will result in a \"no space left on device\" or \"too many open\nfiles\" error.\n\n### kqueue (macOS, all BSD systems)\nkqueue requires opening a file descriptor for every file that's being watched;\nso if you're watching a directory with five files then that's six file\ndescriptors. You will run in to your system's \"max open files\" limit faster on\nthese platforms.\n\nThe sysctl variables `kern.maxfiles` and `kern.maxfilesperproc` can be used to\ncontrol the maximum number of open files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffsnotify%2Ffsnotify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffsnotify%2Ffsnotify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffsnotify%2Ffsnotify/lists"}