1# File system notifications for Go 2 3[![GoDoc](https://godoc.org/github.com/fsnotify/fsnotify?status.svg)](https://godoc.org/github.com/fsnotify/fsnotify) [![Go Report Card](https://goreportcard.com/badge/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 [![Build Status](https://travis-ci.org/fsnotify/fsnotify.svg?branch=master)](https://travis-ci.org/fsnotify/fsnotify) | 16| kqueue | BSD, macOS, iOS\* | Supported [![Build Status](https://travis-ci.org/fsnotify/fsnotify.svg?branch=master)](https://travis-ci.org/fsnotify/fsnotify) | 17| ReadDirectoryChangesW | Windows | Supported [![Build Status](https://travis-ci.org/fsnotify/fsnotify.svg?branch=master)](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