README.md
1# File system notifications for Go
2
3[](https://godoc.org/github.com/fsnotify/fsnotify) [](https://goreportcard.com/report/github.com/fsnotify/fsnotify)
4
5fsnotify utilizes [golang.org/x/sys](https://godoc.org/golang.org/x/sys) rather than `syscall` from the standard library. Ensure you have the latest version installed by running:
6
7```console
8go get -u golang.org/x/sys/...
9```
10
11Cross platform: Windows, Linux, BSD and macOS.
12
13| Adapter | OS | Status |
14| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
15| inotify | Linux 2.6.27 or later, Android\* | Supported [](https://travis-ci.org/fsnotify/fsnotify) |
16| kqueue | BSD, macOS, iOS\* | Supported [](https://travis-ci.org/fsnotify/fsnotify) |
17| ReadDirectoryChangesW | Windows | Supported [](https://travis-ci.org/fsnotify/fsnotify) |
18| FSEvents | macOS | [Planned](https://github.com/fsnotify/fsnotify/issues/11) |
19| FEN | Solaris 11 | [In Progress](https://github.com/fsnotify/fsnotify/issues/12) |
20| fanotify | Linux 2.6.37+ | [Planned](https://github.com/fsnotify/fsnotify/issues/114) |
21| USN Journals | Windows | [Maybe](https://github.com/fsnotify/fsnotify/issues/53) |
22| Polling | *All* | [Maybe](https://github.com/fsnotify/fsnotify/issues/9) |
23
24\* Android and iOS are untested.
25
26Please see [the documentation](https://godoc.org/github.com/fsnotify/fsnotify) and consult the [FAQ](#faq) for usage information.
27
28## API stability
29
30fsnotify is a fork of [howeyc/fsnotify](https://godoc.org/github.com/howeyc/fsnotify) with a new API as of v1.0. The API is based on [this design document](http://goo.gl/MrYxyA).
31
32All [releases](https://github.com/fsnotify/fsnotify/releases) are tagged based on [Semantic Versioning](http://semver.org/). Further API changes are [planned](https://github.com/fsnotify/fsnotify/milestones), and will be tagged with a new major revision number.
33
34Go 1.6 supports dependencies located in the `vendor/` folder. Unless you are creating a library, it is recommended that you copy fsnotify into `vendor/github.com/fsnotify/fsnotify` within your project, and likewise for `golang.org/x/sys`.
35
36## Usage
37
38```go
39package main
40
41import (
42 "log"
43
44 "github.com/fsnotify/fsnotify"
45)
46
47func main() {
48 watcher, err := fsnotify.NewWatcher()
49 if err != nil {
50 log.Fatal(err)
51 }
52 defer watcher.Close()
53
54 done := make(chan bool)
55 go func() {
56 for {
57 select {
58 case event, ok := <-watcher.Events:
59 if !ok {
60 return
61 }
62 log.Println("event:", event)
63 if event.Op&fsnotify.Write == fsnotify.Write {
64 log.Println("modified file:", event.Name)
65 }
66 case err, ok := <-watcher.Errors:
67 if !ok {
68 return
69 }
70 log.Println("error:", err)
71 }
72 }
73 }()
74
75 err = watcher.Add("/tmp/foo")
76 if err != nil {
77 log.Fatal(err)
78 }
79 <-done
80}
81```
82
83## Contributing
84
85Please refer to [CONTRIBUTING][] before opening an issue or pull request.
86
87## Example
88
89See [example_test.go](https://github.com/fsnotify/fsnotify/blob/master/example_test.go).
90
91## FAQ
92
93**When a file is moved to another directory is it still being watched?**
94
95No (it shouldn't be, unless you are watching where it was moved to).
96
97**When I watch a directory, are all subdirectories watched as well?**
98
99No, you must add watches for any directory you want to watch (a recursive watcher is on the roadmap [#18][]).
100
101**Do I have to watch the Error and Event channels in a separate goroutine?**
102
103As of now, yes. Looking into making this single-thread friendly (see [howeyc #7][#7])
104
105**Why am I receiving multiple events for the same file on OS X?**
106
107Spotlight indexing on OS X can result in multiple events (see [howeyc #62][#62]). A temporary workaround is to add your folder(s) to the *Spotlight Privacy settings* until we have a native FSEvents implementation (see [#11][]).
108
109**How many files can be watched at once?**
110
111There are OS-specific limits as to how many watches can be created:
112* Linux: /proc/sys/fs/inotify/max_user_watches contains the limit, reaching this limit results in a "no space left on device" error.
113* BSD / OSX: sysctl variables "kern.maxfiles" and "kern.maxfilesperproc", reaching these limits results in a "too many open files" error.
114
115**Why don't notifications work with NFS filesystems or filesystem in userspace (FUSE)?**
116
117fsnotify requires support from underlying OS to work. The current NFS protocol does not provide network level support for file notifications.
118
119[#62]: https://github.com/howeyc/fsnotify/issues/62
120[#18]: https://github.com/fsnotify/fsnotify/issues/18
121[#11]: https://github.com/fsnotify/fsnotify/issues/11
122[#7]: https://github.com/howeyc/fsnotify/issues/7
123
124[contributing]: https://github.com/fsnotify/fsnotify/blob/master/CONTRIBUTING.md
125
126## Related Projects
127
128* [notify](https://github.com/rjeczalik/notify)
129* [fsevents](https://github.com/fsnotify/fsevents)
130
131
){kind=link}
){kind=link}