209 lines
7.6 KiB
Bash
209 lines
7.6 KiB
Bash
#!/usr/bin/env zsh
|
|
[ "${ZSH_VERSION:-}" = "" ] && echo >&2 "Only works with zsh" && exit 1
|
|
setopt err_exit no_unset pipefail extended_glob
|
|
|
|
# Simple script to update the godoc comments on all watchers. Probably took me
|
|
# more time to write this than doing it manually, but ah well 🙃
|
|
|
|
watcher=$(<<EOF
|
|
// Watcher watches a set of paths, delivering events on a channel.
|
|
//
|
|
// A watcher should not be copied (e.g. pass it by pointer, rather than by
|
|
// value).
|
|
//
|
|
// # Linux notes
|
|
//
|
|
// When a file is removed a Remove event won't be emitted until all file
|
|
// descriptors are closed, and deletes will always emit a Chmod. For example:
|
|
//
|
|
// fp := os.Open("file")
|
|
// os.Remove("file") // Triggers Chmod
|
|
// fp.Close() // Triggers Remove
|
|
//
|
|
// This is the event that inotify sends, so not much can be changed about this.
|
|
//
|
|
// The fs.inotify.max_user_watches sysctl variable specifies the upper limit
|
|
// for the number of watches per user, and fs.inotify.max_user_instances
|
|
// specifies the maximum number of inotify instances per user. Every Watcher you
|
|
// create is an "instance", and every path you add is a "watch".
|
|
//
|
|
// These are also exposed in /proc as /proc/sys/fs/inotify/max_user_watches and
|
|
// /proc/sys/fs/inotify/max_user_instances
|
|
//
|
|
// To increase them you can use sysctl or write the value to the /proc file:
|
|
//
|
|
// # Default values on Linux 5.18
|
|
// sysctl fs.inotify.max_user_watches=124983
|
|
// sysctl fs.inotify.max_user_instances=128
|
|
//
|
|
// To make the changes persist on reboot edit /etc/sysctl.conf or
|
|
// /usr/lib/sysctl.d/50-default.conf (details differ per Linux distro; check
|
|
// your distro's documentation):
|
|
//
|
|
// fs.inotify.max_user_watches=124983
|
|
// fs.inotify.max_user_instances=128
|
|
//
|
|
// Reaching the limit will result in a "no space left on device" or "too many open
|
|
// files" error.
|
|
//
|
|
// # kqueue notes (macOS, BSD)
|
|
//
|
|
// kqueue requires opening a file descriptor for every file that's being watched;
|
|
// so if you're watching a directory with five files then that's six file
|
|
// descriptors. You will run in to your system's "max open files" limit faster on
|
|
// these platforms.
|
|
//
|
|
// 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
|
|
)
|
|
|
|
new=$(<<EOF
|
|
// NewWatcher creates a new Watcher.
|
|
EOF
|
|
)
|
|
|
|
add=$(<<EOF
|
|
// Add starts monitoring the path for changes.
|
|
//
|
|
// A path can only be watched once; attempting to watch it more than once will
|
|
// return an error. Paths that do not yet exist on the filesystem cannot be
|
|
// added. A watch will be automatically removed if the path is deleted.
|
|
//
|
|
// A path will remain watched if it gets renamed to somewhere else on the same
|
|
// filesystem, but the monitor will get removed if the path gets deleted and
|
|
// re-created, or if it's moved to a different filesystem.
|
|
//
|
|
// Notifications on network filesystems (NFS, SMB, FUSE, etc.) or special
|
|
// filesystems (/proc, /sys, etc.) generally don't work.
|
|
//
|
|
// # Watching directories
|
|
//
|
|
// All files in a directory are monitored, including new files that are created
|
|
// after the watcher is started. Subdirectories are not watched (i.e. it's
|
|
// non-recursive).
|
|
//
|
|
// # Watching files
|
|
//
|
|
// Watching individual files (rather than directories) is generally not
|
|
// recommended as many tools update files atomically. Instead of "just" writing
|
|
// to the file a temporary file will be written to first, and if successful the
|
|
// temporary file is moved to to destination removing the original, or some
|
|
// variant thereof. The watcher on the original file is now lost, as it no
|
|
// longer exists.
|
|
//
|
|
// Instead, watch the parent directory and use Event.Name to filter out files
|
|
// you're not interested in. There is an example of this in [cmd/fsnotify/file.go].
|
|
EOF
|
|
)
|
|
|
|
remove=$(<<EOF
|
|
// Remove stops monitoring the path for changes.
|
|
//
|
|
// Directories are always removed non-recursively. For example, if you added
|
|
// /tmp/dir and /tmp/dir/subdir then you will need to remove both.
|
|
//
|
|
// Removing a path that has not yet been added returns [ErrNonExistentWatch].
|
|
EOF
|
|
)
|
|
|
|
close=$(<<EOF
|
|
// Close removes all watches and closes the events channel.
|
|
EOF
|
|
)
|
|
|
|
watchlist=$(<<EOF
|
|
// WatchList returns all paths added with [Add] (and are not yet removed).
|
|
EOF
|
|
)
|
|
|
|
events=$(<<EOF
|
|
// Events sends the filesystem change events.
|
|
//
|
|
// fsnotify can send the following events; a "path" here can refer to a
|
|
// file, directory, symbolic link, or special file like a FIFO.
|
|
//
|
|
// fsnotify.Create A new path was created; this may be followed by one
|
|
// or more Write events if data also gets written to a
|
|
// file.
|
|
//
|
|
// fsnotify.Remove A path was removed.
|
|
//
|
|
// fsnotify.Rename A path was renamed. A rename is always sent with the
|
|
// old path as Event.Name, and a Create event will be
|
|
// sent with the new name. Renames are only sent for
|
|
// paths that are currently watched; e.g. moving an
|
|
// unmonitored file into a monitored directory will
|
|
// show up as just a Create. Similarly, renaming a file
|
|
// to outside a monitored directory will show up as
|
|
// only a Rename.
|
|
//
|
|
// fsnotify.Write A file or named pipe was written to. A Truncate will
|
|
// also trigger a Write. A single "write action"
|
|
// initiated by the user may show up as one or multiple
|
|
// writes, depending on when the system syncs things to
|
|
// disk. For example when compiling a large Go program
|
|
// you may get hundreds of Write events, so you
|
|
// probably want to wait until you've stopped receiving
|
|
// them (see the dedup example in cmd/fsnotify).
|
|
//
|
|
// fsnotify.Chmod Attributes were changed. On Linux this is also sent
|
|
// when a file is removed (or more accurately, when a
|
|
// link to an inode is removed). On kqueue it's sent
|
|
// and on kqueue when a file is truncated. On Windows
|
|
// it's never sent.
|
|
EOF
|
|
)
|
|
|
|
errors=$(<<EOF
|
|
// Errors sends any errors.
|
|
EOF
|
|
)
|
|
|
|
set-cmt() {
|
|
local pat=$1
|
|
local cmt=$2
|
|
|
|
IFS=$'\n' local files=($(grep -n $pat backend_*~*_test.go))
|
|
for f in $files; do
|
|
IFS=':' local fields=($=f)
|
|
local file=$fields[1]
|
|
local end=$(( $fields[2] - 1 ))
|
|
|
|
# Find start of comment.
|
|
local start=0
|
|
IFS=$'\n' local lines=($(head -n$end $file))
|
|
for (( i = 1; i <= $#lines; i++ )); do
|
|
local line=$lines[-$i]
|
|
if ! grep -q '^[[:space:]]*//' <<<$line; then
|
|
start=$(( end - (i - 2) ))
|
|
break
|
|
fi
|
|
done
|
|
|
|
head -n $(( start - 1 )) $file >/tmp/x
|
|
print -r -- $cmt >>/tmp/x
|
|
tail -n+$(( end + 1 )) $file >>/tmp/x
|
|
mv /tmp/x $file
|
|
done
|
|
}
|
|
|
|
set-cmt '^type Watcher struct ' $watcher
|
|
set-cmt '^func NewWatcher(' $new
|
|
set-cmt '^func (w \*Watcher) Add(' $add
|
|
set-cmt '^func (w \*Watcher) Remove(' $remove
|
|
set-cmt '^func (w \*Watcher) Close(' $close
|
|
set-cmt '^func (w \*Watcher) WatchList(' $watchlist
|
|
set-cmt '^[[:space:]]*Events *chan Event$' $events
|
|
set-cmt '^[[:space:]]*Errors *chan error$' $errors
|