Skip to content

Latest commit

 

History

History
153 lines (109 loc) · 5.5 KB

README.md

File metadata and controls

153 lines (109 loc) · 5.5 KB
Raw

File system notifications for Go

Go Reference Go Report Card

Cross platform

fsnotify supports Windows, Linux, BSD and macOS with a common API.

Adapter OS Status
inotify Linux 2.6.32+, Android* Supported
kqueue BSD, macOS, iOS* Supported
ReadDirectoryChangesW Windows Supported
FSEvents macOS Planned
FEN Solaris 11 In Progress
fanotify Linux 2.6.37+ Maybe
USN Journals Windows Maybe
Polling All Maybe

* Android and iOS are untested.

fsnotify requires Go 1.16 or newer. Please see the documentation and consult the FAQ for usage information.

NOTE: fsnotify utilizes golang.org/x/sys rather than syscall from the standard library.

API stability

fsnotify is a fork of howeyc/fsnotify with a new API as of v1.0. The API is based on this design document.

All releases are tagged based on Semantic Versioning.

Usage

package main

import (
	"log"

	"github.com/fsnotify/fsnotify"
)

func main() {
	watcher, err := fsnotify.NewWatcher()
	if err != nil {
		log.Fatal(err)
	}
	defer watcher.Close()

	done := make(chan bool)
	go func() {
		for {
			select {
			case event, ok := <-watcher.Events:
				if !ok {
					return
				}
				log.Println("event:", event)
				if event.Op&fsnotify.Write == fsnotify.Write {
					log.Println("modified file:", event.Name)
				}
			case err, ok := <-watcher.Errors:
				if !ok {
					return
				}
				log.Println("error:", err)
			}
		}
	}()

	err = watcher.Add("/tmp/foo")
	if err != nil {
		log.Fatal(err)
	}
	<-done
}

Contributing

Please refer to CONTRIBUTING before opening an issue or pull request.

FAQ

When a file is moved to another directory is it still being watched?

No (it shouldn't be, unless you are watching where it was moved to).

When I watch a directory, are all subdirectories watched as well?

No, you must add watches for any directory you want to watch (a recursive watcher is on the roadmap #18).

Do I have to watch the Error and Event channels in a separate goroutine?

As of now, yes. Looking into making this single-thread friendly (see howeyc #7)

Why am I receiving multiple events for the same file on macOS?

Spotlight indexing on macOS can result in multiple events (see howeyc #62). A temporary workaround is to add your folder(s) to the Spotlight Privacy settings until we have a native FSEvents implementation (see #11).

How many files can be watched at once?

There are OS-specific limits as to how many watches can be created:

  • Linux: 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 proc file:

    # The 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 (some systemd systems):

    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.

  • BSD / macOS: sysctl variables kern.maxfiles and kern.maxfilesperproc, reaching these limits results in a "too many open files" error.

Why don't notifications work with NFS, SMB, or filesystem in userspace (FUSE)?

fsnotify requires support from underlying OS to work. The current NFS and SMB protocols does not provide network level support for file notifications.

Related Projects