| #!/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 |
