Skip to content

Commit 8878587

Browse files
arp242arp242
committed
Tweak the docs a bit
1 parent 89b4cf1 commit 8878587

12 files changed

Lines changed: 114 additions & 92 deletions

‎README.md‎

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
fsnotify is a Go library to provide cross-platform filesystem notifications on
22
Windows, Linux, macOS, and BSD systems.
33

4-
fsnotify requires Go 1.16 or newer.
4+
Go 1.16 or newer is required; the full documentation is at
5+
https://pkg.go.dev/github.com/fsnotify/fsnotify
56

6-
API docs: https://pkg.go.dev/github.com/fsnotify/fsnotify
7-
8-
It's best to read the documentation at pkg.go.dev, as it's pinned to the last
7+
**It's best to read the documentation at pkg.go.dev, as it's pinned to the last
98
released version, whereas this README is for the last development version which
10-
may include additions/changes.
9+
may include additions/changes.**
1110

1211
---
1312

@@ -89,15 +88,15 @@ FAQ
8988
### Will a file still be watched when it's moved to another directory?
9089
No, not unless you are watching the location it was moved to.
9190

92-
### Are all subdirectories watched too?
91+
### Are subdirectories watched too?
9392
No, you must add watches for any directory you want to watch (a recursive
9493
watcher is on the roadmap: [#18]).
9594

9695
[#18]: https://github.com/fsnotify/fsnotify/issues/18
9796

98-
### Do I have to watch the Error and Event channels in a separate goroutine?
99-
As of now, yes (you can read both channels in the same goroutine, you don't need
100-
a separate goroutine for both channels; see the example).
97+
### Do I have to watch the Error and Event channels in a goroutine?
98+
As of now, yes (you can read both channels in the same goroutine using `select`,
99+
you don't need a separate goroutine for both channels; see the example).
101100

102101
### Why don't notifications work with NFS, SMB, FUSE, /proc, or /sys?
103102
fsnotify requires support from underlying OS to work. The current NFS and SMB
@@ -112,18 +111,20 @@ Platform-specific notes
112111
-----------------------
113112
### Linux
114113
When a file is removed a REMOVE event won't be emitted until all file
115-
descriptors are closed. It will emit a CHMOD though:
114+
descriptors are closed; it will emit a CHMOD instead:
116115

117116
fp := os.Open("file")
118117
os.Remove("file") // CHMOD
119118
fp.Close() // REMOVE
120119

120+
This is the event that inotify sends, so not much can be changed about this.
121+
121122
The `fs.inotify.max_user_watches` sysctl variable specifies the upper limit for
122123
the number of watches per user, and `fs.inotify.max_user_instances` specifies
123124
the maximum number of inotify instances per user. Every Watcher you create is an
124125
"instance", and every path you add is a "watch".
125126

126-
These are also exposed in /proc as `/proc/sys/fs/inotify/max_user_watches` and
127+
These are also exposed in `/proc` as `/proc/sys/fs/inotify/max_user_watches` and
127128
`/proc/sys/fs/inotify/max_user_instances`
128129

129130
To increase them you can use `sysctl` or write the value to proc file:
@@ -133,7 +134,8 @@ To increase them you can use `sysctl` or write the value to proc file:
133134
sysctl fs.inotify.max_user_instances=128
134135

135136
To make the changes persist on reboot edit `/etc/sysctl.conf` or
136-
`/usr/lib/sysctl.d/50-default.conf` (some systemd systems):
137+
`/usr/lib/sysctl.d/50-default.conf` (details differ per Linux distro; check your
138+
distro's documentation):
137139

138140
fs.inotify.max_user_watches=124983
139141
fs.inotify.max_user_instances=128
@@ -157,8 +159,3 @@ have a native FSEvents implementation (see [#11]).
157159

158160
[#11]: https://github.com/fsnotify/fsnotify/issues/11
159161
[#15]: https://github.com/fsnotify/fsnotify/issues/15
160-
161-
Related Projects
162-
----------------
163-
- [notify](https://github.com/rjeczalik/notify)
164-
- [fsevents](https://github.com/fsnotify/fsevents)

‎backend_fen.go‎

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import (
77
"errors"
88
)
99

10-
// Watcher watches a set of files, delivering events to a channel.
10+
// Watcher watches a set of paths, delivering events on a channel.
1111
//
1212
// A watcher should not be copied (e.g. pass it by pointer, rather than by
1313
// value).
@@ -21,6 +21,8 @@ import (
2121
// os.Remove("file") // Triggers Chmod
2222
// fp.Close() // Triggers Remove
2323
//
24+
// This is the event that inotify sends, so not much can be changed about this.
25+
//
2426
// The fs.inotify.max_user_watches sysctl variable specifies the upper limit
2527
// for the number of watches per user, and fs.inotify.max_user_instances
2628
// specifies the maximum number of inotify instances per user. Every Watcher you
@@ -36,7 +38,8 @@ import (
3638
// sysctl fs.inotify.max_user_instances=128
3739
//
3840
// To make the changes persist on reboot edit /etc/sysctl.conf or
39-
// /usr/lib/sysctl.d/50-default.conf (on some systemd systems):
41+
// /usr/lib/sysctl.d/50-default.conf (details differ per Linux distro; check
42+
// your distro's documentation):
4043
//
4144
// fs.inotify.max_user_watches=124983
4245
// fs.inotify.max_user_instances=128
@@ -67,7 +70,7 @@ type Watcher struct {
6770
// Events sends the filesystem change events.
6871
//
6972
// fsnotify can send the following events; a "path" here can refer to a
70-
// file, directory, symbolic link, or special files like a FIFO.
73+
// file, directory, symbolic link, or special file like a FIFO.
7174
//
7275
// fsnotify.Create A new path was created; this may be followed by one
7376
// or more Write events if data also gets written to a
@@ -76,7 +79,7 @@ type Watcher struct {
7679
// fsnotify.Remove A path was removed.
7780
//
7881
// fsnotify.Rename A path was renamed. A rename is always sent with the
79-
// old path as [Event.Name], and a Create event will be
82+
// old path as Event.Name, and a Create event will be
8083
// sent with the new name. Renames are only sent for
8184
// paths that are currently watched; e.g. moving an
8285
// unmonitored file into a monitored directory will
@@ -93,10 +96,11 @@ type Watcher struct {
9396
// probably want to wait until you've stopped receiving
9497
// them (see the dedup example in cmd/fsnotify).
9598
//
96-
// fsnotify.Chmod Attributes were changes (never sent on Windows). On
97-
// Linux this is also sent when a file is removed (or
98-
// more accurately, when a link to an inode is
99-
// removed), and on kqueue when a file is truncated.
99+
// fsnotify.Chmod Attributes were changed. On Linux this is also sent
100+
// when a file is removed (or more accurately, when a
101+
// link to an inode is removed). On kqueue it's sent
102+
// and on kqueue when a file is truncated. On Windows
103+
// it's never sent.
100104
Events chan Event
101105

102106
// Errors sends any errors.
@@ -121,7 +125,7 @@ func (w *Watcher) Close() error {
121125
//
122126
// A path will remain watched if it gets renamed to somewhere else on the same
123127
// filesystem, but the monitor will get removed if the path gets deleted and
124-
// re-created.
128+
// re-created, or if it's moved to a different filesystem.
125129
//
126130
// Notifications on network filesystems (NFS, SMB, FUSE, etc.) or special
127131
// filesystems (/proc, /sys, etc.) generally don't work.
@@ -137,12 +141,12 @@ func (w *Watcher) Close() error {
137141
// Watching individual files (rather than directories) is generally not
138142
// recommended as many tools update files atomically. Instead of "just" writing
139143
// to the file a temporary file will be written to first, and if successful the
140-
// temporary file is moved to to destination, removing the original, or some
144+
// temporary file is moved to to destination removing the original, or some
141145
// variant thereof. The watcher on the original file is now lost, as it no
142146
// longer exists.
143147
//
144-
// Instead, watch the parent directory and use [Event.Name] to filter out files
145-
// you're not interested in. There is an example of this in cmd/fsnotify/file.go
148+
// Instead, watch the parent directory and use Event.Name to filter out files
149+
// you're not interested in. There is an example of this in [cmd/fsnotify/file.go].
146150
func (w *Watcher) Add(name string) error {
147151
return nil
148152
}

‎backend_inotify.go‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import (
1616
"golang.org/x/sys/unix"
1717
)
1818

19-
// Watcher watches a set of files, delivering events to a channel.
19+
// Watcher watches a set of paths, delivering events on a channel.
2020
//
2121
// A watcher should not be copied (e.g. pass it by pointer, rather than by
2222
// value).
@@ -30,6 +30,8 @@ import (
3030
// os.Remove("file") // Triggers Chmod
3131
// fp.Close() // Triggers Remove
3232
//
33+
// This is the event that inotify sends, so not much can be changed about this.
34+
//
3335
// The fs.inotify.max_user_watches sysctl variable specifies the upper limit
3436
// for the number of watches per user, and fs.inotify.max_user_instances
3537
// specifies the maximum number of inotify instances per user. Every Watcher you
@@ -45,7 +47,8 @@ import (
4547
// sysctl fs.inotify.max_user_instances=128
4648
//
4749
// To make the changes persist on reboot edit /etc/sysctl.conf or
48-
// /usr/lib/sysctl.d/50-default.conf (on some systemd systems):
50+
// /usr/lib/sysctl.d/50-default.conf (details differ per Linux distro; check
51+
// your distro's documentation):
4952
//
5053
// fs.inotify.max_user_watches=124983
5154
// fs.inotify.max_user_instances=128
@@ -76,7 +79,7 @@ type Watcher struct {
7679
// Events sends the filesystem change events.
7780
//
7881
// fsnotify can send the following events; a "path" here can refer to a
79-
// file, directory, symbolic link, or special files like a FIFO.
82+
// file, directory, symbolic link, or special file like a FIFO.
8083
//
8184
// fsnotify.Create A new path was created; this may be followed by one
8285
// or more Write events if data also gets written to a
@@ -85,7 +88,7 @@ type Watcher struct {
8588
// fsnotify.Remove A path was removed.
8689
//
8790
// fsnotify.Rename A path was renamed. A rename is always sent with the
88-
// old path as [Event.Name], and a Create event will be
91+
// old path as Event.Name, and a Create event will be
8992
// sent with the new name. Renames are only sent for
9093
// paths that are currently watched; e.g. moving an
9194
// unmonitored file into a monitored directory will
@@ -102,10 +105,11 @@ type Watcher struct {
102105
// probably want to wait until you've stopped receiving
103106
// them (see the dedup example in cmd/fsnotify).
104107
//
105-
// fsnotify.Chmod Attributes were changes (never sent on Windows). On
106-
// Linux this is also sent when a file is removed (or
107-
// more accurately, when a link to an inode is
108-
// removed), and on kqueue when a file is truncated.
108+
// fsnotify.Chmod Attributes were changed. On Linux this is also sent
109+
// when a file is removed (or more accurately, when a
110+
// link to an inode is removed). On kqueue it's sent
111+
// and on kqueue when a file is truncated. On Windows
112+
// it's never sent.
109113
Events chan Event
110114

111115
// Errors sends any errors.
@@ -209,7 +213,7 @@ func (w *Watcher) Close() error {
209213
//
210214
// A path will remain watched if it gets renamed to somewhere else on the same
211215
// filesystem, but the monitor will get removed if the path gets deleted and
212-
// re-created.
216+
// re-created, or if it's moved to a different filesystem.
213217
//
214218
// Notifications on network filesystems (NFS, SMB, FUSE, etc.) or special
215219
// filesystems (/proc, /sys, etc.) generally don't work.
@@ -225,12 +229,12 @@ func (w *Watcher) Close() error {
225229
// Watching individual files (rather than directories) is generally not
226230
// recommended as many tools update files atomically. Instead of "just" writing
227231
// to the file a temporary file will be written to first, and if successful the
228-
// temporary file is moved to to destination, removing the original, or some
232+
// temporary file is moved to to destination removing the original, or some
229233
// variant thereof. The watcher on the original file is now lost, as it no
230234
// longer exists.
231235
//
232-
// Instead, watch the parent directory and use [Event.Name] to filter out files
233-
// you're not interested in. There is an example of this in cmd/fsnotify/file.go
236+
// Instead, watch the parent directory and use Event.Name to filter out files
237+
// you're not interested in. There is an example of this in [cmd/fsnotify/file.go].
234238
func (w *Watcher) Add(name string) error {
235239
name = filepath.Clean(name)
236240
if w.isClosed() {
@@ -312,7 +316,7 @@ func (w *Watcher) Remove(name string) error {
312316
return nil
313317
}
314318

315-
// WatchList returns all paths added with Add() (and are not yet removed).
319+
// WatchList returns all paths added with [Add] (and are not yet removed).
316320
func (w *Watcher) WatchList() []string {
317321
w.mu.Lock()
318322
defer w.mu.Unlock()

‎backend_kqueue.go‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import (
1414
"golang.org/x/sys/unix"
1515
)
1616

17-
// Watcher watches a set of files, delivering events to a channel.
17+
// Watcher watches a set of paths, delivering events on a channel.
1818
//
1919
// A watcher should not be copied (e.g. pass it by pointer, rather than by
2020
// value).
@@ -28,6 +28,8 @@ import (
2828
// os.Remove("file") // Triggers Chmod
2929
// fp.Close() // Triggers Remove
3030
//
31+
// This is the event that inotify sends, so not much can be changed about this.
32+
//
3133
// The fs.inotify.max_user_watches sysctl variable specifies the upper limit
3234
// for the number of watches per user, and fs.inotify.max_user_instances
3335
// specifies the maximum number of inotify instances per user. Every Watcher you
@@ -43,7 +45,8 @@ import (
4345
// sysctl fs.inotify.max_user_instances=128
4446
//
4547
// To make the changes persist on reboot edit /etc/sysctl.conf or
46-
// /usr/lib/sysctl.d/50-default.conf (on some systemd systems):
48+
// /usr/lib/sysctl.d/50-default.conf (details differ per Linux distro; check
49+
// your distro's documentation):
4750
//
4851
// fs.inotify.max_user_watches=124983
4952
// fs.inotify.max_user_instances=128
@@ -74,7 +77,7 @@ type Watcher struct {
7477
// Events sends the filesystem change events.
7578
//
7679
// fsnotify can send the following events; a "path" here can refer to a
77-
// file, directory, symbolic link, or special files like a FIFO.
80+
// file, directory, symbolic link, or special file like a FIFO.
7881
//
7982
// fsnotify.Create A new path was created; this may be followed by one
8083
// or more Write events if data also gets written to a
@@ -83,7 +86,7 @@ type Watcher struct {
8386
// fsnotify.Remove A path was removed.
8487
//
8588
// fsnotify.Rename A path was renamed. A rename is always sent with the
86-
// old path as [Event.Name], and a Create event will be
89+
// old path as Event.Name, and a Create event will be
8790
// sent with the new name. Renames are only sent for
8891
// paths that are currently watched; e.g. moving an
8992
// unmonitored file into a monitored directory will
@@ -100,10 +103,11 @@ type Watcher struct {
100103
// probably want to wait until you've stopped receiving
101104
// them (see the dedup example in cmd/fsnotify).
102105
//
103-
// fsnotify.Chmod Attributes were changes (never sent on Windows). On
104-
// Linux this is also sent when a file is removed (or
105-
// more accurately, when a link to an inode is
106-
// removed), and on kqueue when a file is truncated.
106+
// fsnotify.Chmod Attributes were changed. On Linux this is also sent
107+
// when a file is removed (or more accurately, when a
108+
// link to an inode is removed). On kqueue it's sent
109+
// and on kqueue when a file is truncated. On Windows
110+
// it's never sent.
107111
Events chan Event
108112

109113
// Errors sends any errors.
@@ -241,7 +245,7 @@ func (w *Watcher) Close() error {
241245
//
242246
// A path will remain watched if it gets renamed to somewhere else on the same
243247
// filesystem, but the monitor will get removed if the path gets deleted and
244-
// re-created.
248+
// re-created, or if it's moved to a different filesystem.
245249
//
246250
// Notifications on network filesystems (NFS, SMB, FUSE, etc.) or special
247251
// filesystems (/proc, /sys, etc.) generally don't work.
@@ -257,12 +261,12 @@ func (w *Watcher) Close() error {
257261
// Watching individual files (rather than directories) is generally not
258262
// recommended as many tools update files atomically. Instead of "just" writing
259263
// to the file a temporary file will be written to first, and if successful the
260-
// temporary file is moved to to destination, removing the original, or some
264+
// temporary file is moved to to destination removing the original, or some
261265
// variant thereof. The watcher on the original file is now lost, as it no
262266
// longer exists.
263267
//
264-
// Instead, watch the parent directory and use [Event.Name] to filter out files
265-
// you're not interested in. There is an example of this in cmd/fsnotify/file.go
268+
// Instead, watch the parent directory and use Event.Name to filter out files
269+
// you're not interested in. There is an example of this in [cmd/fsnotify/file.go].
266270
func (w *Watcher) Add(name string) error {
267271
w.mu.Lock()
268272
w.userWatches[name] = struct{}{}
@@ -332,7 +336,7 @@ func (w *Watcher) Remove(name string) error {
332336
return nil
333337
}
334338

335-
// WatchList returns all paths added with Add() (and are not yet removed).
339+
// WatchList returns all paths added with [Add] (and are not yet removed).
336340
func (w *Watcher) WatchList() []string {
337341
w.mu.Lock()
338342
defer w.mu.Unlock()

‎backend_other.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ func (w *Watcher) Close() error {
2929
//
3030
// A path will remain watched if it gets renamed to somewhere else on the same
3131
// filesystem, but the monitor will get removed if the path gets deleted and
32-
// re-created.
32+
// re-created, or if it's moved to a different filesystem.
3333
//
3434
// Notifications on network filesystems (NFS, SMB, FUSE, etc.) or special
3535
// filesystems (/proc, /sys, etc.) generally don't work.
@@ -45,12 +45,12 @@ func (w *Watcher) Close() error {
4545
// Watching individual files (rather than directories) is generally not
4646
// recommended as many tools update files atomically. Instead of "just" writing
4747
// to the file a temporary file will be written to first, and if successful the
48-
// temporary file is moved to to destination, removing the original, or some
48+
// temporary file is moved to to destination removing the original, or some
4949
// variant thereof. The watcher on the original file is now lost, as it no
5050
// longer exists.
5151
//
52-
// Instead, watch the parent directory and use [Event.Name] to filter out files
53-
// you're not interested in. There is an example of this in cmd/fsnotify/file.go
52+
// Instead, watch the parent directory and use Event.Name to filter out files
53+
// you're not interested in. There is an example of this in [cmd/fsnotify/file.go].
5454
func (w *Watcher) Add(name string) error {
5555
return nil
5656
}

0 commit comments

Comments
 (0)