Document events a bit better

Fixes #529

diff --git a/README.md b/README.md
index 91080ba24fdca12fe7597a7c3c055fe02d2eb36e..e67fb8bd30654b75c6ec18280f76354114bc0744 100644 (file)
--- 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 c09ec3c0fac67c49c5808fcfbd66b2e1a0f82080..95fbe99a9bf7e511cf82476db2383d1ece53389e 100644 (file)
--- 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 d813453ec7310fdeb2d0c477e893a957f43743cd..a96c3adf349f6903127163a20b56c5a5174fa178 100644 (file)
--- 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 8f370d18eb4bcc7743128c434eb9514451633076..cbe4778b245d92ed45b419444650e3336670cad4 100644 (file)
--- 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 4429c8339a4099e2624ff1e203d91a280b274847..fc6bacae54ba91bd977c56796c007cdac10ca0a4 100644 (file)
--- 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 24b5b840480046b7e6650030b9d887c7b1166159..ba5e95817a3f0ba9b238a4dbbda9df0df319e0bb 100644 (file)
--- 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 30653e3bb59bf526fc965b56b187d7d042881198..4f7f445fb1a4cf5a7a49ac615abe0bea169e991e 100644 (file)
--- 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 25bc760f8c71fd1390310e256af1241b66fede54..19aa1edf5041709d5eecea29bccfef7c15a90b56 100755 (executable)
--- a/mkdoc.zsh
+++ b/mkdoc.zsh
@@ -56,15 +56,6 @@ watcher=$(<<EOF
 // 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
 EOF
 )
 
@@ -172,7 +163,7 @@ EOF
 errors=$(<<EOF
        // 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.