From f07448894a45e3879d8d46c9ade8a7b94c9957d3 Mon Sep 17 00:00:00 2001 From: Martin Tournoij Date: Mon, 17 Oct 2022 08:41:35 +0200 Subject: [PATCH] Document events a bit better Fixes #529 --- README.md | 31 +++++++++++++++++++++---------- backend_fen.go | 11 +---------- backend_inotify.go | 11 +---------- backend_kqueue.go | 11 +---------- backend_other.go | 11 +---------- backend_windows.go | 11 +---------- fsnotify.go | 17 +++++++++++++++++ mkdoc.zsh | 11 +---------- 8 files changed, 44 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index 91080ba..e67fb8b 100644 --- a/README.md +++ b/README.md @@ -14,14 +14,17 @@ Platform support: | kqueue | BSD, macOS | Supported | | ReadDirectoryChangesW | Windows | Supported | | FEN | illumos | Supported in main branch | -| FSEvents | macOS | [Not yet](https://github.com/fsnotify/fsnotify/issues/11) | +| FSEvents | macOS | [Needs support in x/sys/unix][fsevents] | | fanotify | Linux 5.9+ | [Not yet](https://github.com/fsnotify/fsnotify/issues/114) | -| USN Journals | Windows | [Maybe](https://github.com/fsnotify/fsnotify/issues/53) | +| USN Journals | Windows | [Needs support in x/sys/windows][usn] | | Polling | *All* | [Not yet](https://github.com/fsnotify/fsnotify/issues/9) | Linux, macOS, and illumos should include Android, iOS, and Solaris, but these are currently untested. +[fsevents]: https://github.com/fsnotify/fsnotify/issues/11#issuecomment-1279133120 +[usn]: https://github.com/fsnotify/fsnotify/issues/53#issuecomment-1279829847 + Usage ----- A basic example: @@ -80,6 +83,9 @@ run with: % go run ./cmd/fsnotify +Further detailed documentation can be found in godoc: +https://pkg.go.dev/github.com/fsnotify/fsnotify + FAQ --- ### Will a file still be watched when it's moved to another directory? @@ -104,6 +110,19 @@ This could be fixed with a polling watcher ([#9]), but it's not yet implemented. [#9]: https://github.com/fsnotify/fsnotify/issues/9 +### Why do I get many Chmod events? +Some programs may generate a lot of attribute changes; for example Spotlight on +macOS, anti-virus programs, backup applications, and some others are known to do +this. As a rule, it's typically best to ignore Chmod events. They're often not +useful, and tend to cause problems. + +Spotlight indexing on macOS can result in multiple events (see [#15]). A +temporary workaround is to add your folder(s) to the *Spotlight Privacy +settings* until we have a native FSEvents implementation (see [#11]). + +[#11]: https://github.com/fsnotify/fsnotify/issues/11 +[#15]: https://github.com/fsnotify/fsnotify/issues/15 + Platform-specific notes ----------------------- ### Linux @@ -148,11 +167,3 @@ these platforms. The sysctl variables `kern.maxfiles` and `kern.maxfilesperproc` can be used to control the maximum number of open files. - -### macOS -Spotlight indexing on macOS can result in multiple events (see [#15]). A temporary -workaround is to add your folder(s) to the *Spotlight Privacy settings* until we -have a native FSEvents implementation (see [#11]). - -[#11]: https://github.com/fsnotify/fsnotify/issues/11 -[#15]: https://github.com/fsnotify/fsnotify/issues/15 diff --git a/backend_fen.go b/backend_fen.go index c09ec3c..95fbe99 100644 --- a/backend_fen.go +++ b/backend_fen.go @@ -63,15 +63,6 @@ import ( // The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to // control the maximum number of open files, as well as /etc/login.conf on BSD // systems. -// -// # macOS notes -// -// Spotlight indexing on macOS can result in multiple events (see [#15]). A -// temporary workaround is to add your folder(s) to the "Spotlight Privacy -// Settings" until we have a native FSEvents implementation (see [#11]). -// -// [#11]: https://github.com/fsnotify/fsnotify/issues/11 -// [#15]: https://github.com/fsnotify/fsnotify/issues/15 type Watcher struct { // Events sends the filesystem change events. // @@ -111,7 +102,7 @@ type Watcher struct { // Errors sends any errors. // - // [ErrEventOverflow] is used to indicate ther are too many events: + // [ErrEventOverflow] is used to indicate there are too many events: // // - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl) // - windows: The buffer size is too small. diff --git a/backend_inotify.go b/backend_inotify.go index d813453..a96c3ad 100644 --- a/backend_inotify.go +++ b/backend_inotify.go @@ -66,15 +66,6 @@ import ( // The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to // control the maximum number of open files, as well as /etc/login.conf on BSD // systems. -// -// # macOS notes -// -// Spotlight indexing on macOS can result in multiple events (see [#15]). A -// temporary workaround is to add your folder(s) to the "Spotlight Privacy -// Settings" until we have a native FSEvents implementation (see [#11]). -// -// [#11]: https://github.com/fsnotify/fsnotify/issues/11 -// [#15]: https://github.com/fsnotify/fsnotify/issues/15 type Watcher struct { // Events sends the filesystem change events. // @@ -114,7 +105,7 @@ type Watcher struct { // Errors sends any errors. // - // [ErrEventOverflow] is used to indicate ther are too many events: + // [ErrEventOverflow] is used to indicate there are too many events: // // - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl) // - windows: The buffer size is too small. diff --git a/backend_kqueue.go b/backend_kqueue.go index 8f370d1..cbe4778 100644 --- a/backend_kqueue.go +++ b/backend_kqueue.go @@ -64,15 +64,6 @@ import ( // The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to // control the maximum number of open files, as well as /etc/login.conf on BSD // systems. -// -// # macOS notes -// -// Spotlight indexing on macOS can result in multiple events (see [#15]). A -// temporary workaround is to add your folder(s) to the "Spotlight Privacy -// Settings" until we have a native FSEvents implementation (see [#11]). -// -// [#11]: https://github.com/fsnotify/fsnotify/issues/11 -// [#15]: https://github.com/fsnotify/fsnotify/issues/15 type Watcher struct { // Events sends the filesystem change events. // @@ -112,7 +103,7 @@ type Watcher struct { // Errors sends any errors. // - // [ErrEventOverflow] is used to indicate ther are too many events: + // [ErrEventOverflow] is used to indicate there are too many events: // // - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl) // - windows: The buffer size is too small. diff --git a/backend_other.go b/backend_other.go index 4429c83..fc6baca 100644 --- a/backend_other.go +++ b/backend_other.go @@ -58,15 +58,6 @@ import ( // The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to // control the maximum number of open files, as well as /etc/login.conf on BSD // systems. -// -// # macOS notes -// -// Spotlight indexing on macOS can result in multiple events (see [#15]). A -// temporary workaround is to add your folder(s) to the "Spotlight Privacy -// Settings" until we have a native FSEvents implementation (see [#11]). -// -// [#11]: https://github.com/fsnotify/fsnotify/issues/11 -// [#15]: https://github.com/fsnotify/fsnotify/issues/15 type Watcher struct { // Events sends the filesystem change events. // @@ -106,7 +97,7 @@ type Watcher struct { // Errors sends any errors. // - // [ErrEventOverflow] is used to indicate ther are too many events: + // [ErrEventOverflow] is used to indicate there are too many events: // // - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl) // - windows: The buffer size is too small. diff --git a/backend_windows.go b/backend_windows.go index 24b5b84..ba5e958 100644 --- a/backend_windows.go +++ b/backend_windows.go @@ -67,15 +67,6 @@ import ( // The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to // control the maximum number of open files, as well as /etc/login.conf on BSD // systems. -// -// # macOS notes -// -// Spotlight indexing on macOS can result in multiple events (see [#15]). A -// temporary workaround is to add your folder(s) to the "Spotlight Privacy -// Settings" until we have a native FSEvents implementation (see [#11]). -// -// [#11]: https://github.com/fsnotify/fsnotify/issues/11 -// [#15]: https://github.com/fsnotify/fsnotify/issues/15 type Watcher struct { // Events sends the filesystem change events. // @@ -115,7 +106,7 @@ type Watcher struct { // Errors sends any errors. // - // [ErrEventOverflow] is used to indicate ther are too many events: + // [ErrEventOverflow] is used to indicate there are too many events: // // - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl) // - windows: The buffer size is too small. diff --git a/fsnotify.go b/fsnotify.go index 30653e3..4f7f445 100644 --- a/fsnotify.go +++ b/fsnotify.go @@ -37,10 +37,27 @@ type Op uint32 // The operations fsnotify can trigger; see the documentation on [Watcher] for a // full description, and check them with [Event.Has]. const ( + // A new pathname was created. Create Op = 1 << iota + + // The pathname was written to; this does *not* mean the write has finished, + // and a write can be followed by more writes. Write + + // The path was removed; any watches on it will be removed. Some "remove" + // operations may trigger a Rename if the file is actually moved (for + // example "remove to trash" is often a rename). Remove + + // The path was renamed to something else; any watched on it will be + // removed. Rename + + // File attributes were changed. + // + // It's generally not recommended to take action on this event, as it may + // get triggered very frequently by some software. For example, Spotlight + // indexing on macOS, anti-virus software, backup software, etc. Chmod ) diff --git a/mkdoc.zsh b/mkdoc.zsh index 25bc760..19aa1ed 100755 --- a/mkdoc.zsh +++ b/mkdoc.zsh @@ -56,15 +56,6 @@ watcher=$(<