vendor/github.com/fsnotify/fsnotify/README.md

   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
   5 fsnotify 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
   8 go get -u golang.org/x/sys/...
   9 ```
  10
  11 Cross 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://ci.appveyor.com/api/projects/status/ivwjubaih4r0udeh/branch/master?svg=true)](https://ci.appveyor.com/project/NathanYoungman/fsnotify/branch/master)|
  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+ | |
  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
  26 Please see [the documentation](https://godoc.org/github.com/fsnotify/fsnotify) and consult the [FAQ](#faq) for usage information.
  27
  28 ## API stability
  29
  30 fsnotify 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
  32 All [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
  34 Go 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 ## Contributing
  37
  38 Please refer to [CONTRIBUTING][] before opening an issue or pull request.
  39
  40 ## Example
  41
  42 See [example_test.go](https://github.com/fsnotify/fsnotify/blob/master/example_test.go).
  43
  44 ## FAQ
  45
  46 **When a file is moved to another directory is it still being watched?**
  47
  48 No (it shouldn't be, unless you are watching where it was moved to).
  49
  50 **When I watch a directory, are all subdirectories watched as well?**
  51
  52 No, you must add watches for any directory you want to watch (a recursive watcher is on the roadmap [#18][]).
  53
  54 **Do I have to watch the Error and Event channels in a separate goroutine?**
  55
  56 As of now, yes. Looking into making this single-thread friendly (see [howeyc #7][#7])
  57
  58 **Why am I receiving multiple events for the same file on OS X?**
  59
  60 Spotlight 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][]).
  61
  62 **How many files can be watched at once?**
  63
  64 There are OS-specific limits as to how many watches can be created:
  65 * Linux: /proc/sys/fs/inotify/max_user_watches contains the limit, reaching this limit results in a "no space left on device" error.
  66 * BSD / OSX: sysctl variables "kern.maxfiles" and "kern.maxfilesperproc", reaching these limits results in a "too many open files" error.
  67
  68 [#62]: https://github.com/howeyc/fsnotify/issues/62
  69 [#18]: https://github.com/fsnotify/fsnotify/issues/18
  70 [#11]: https://github.com/fsnotify/fsnotify/issues/11
  71 [#7]: https://github.com/howeyc/fsnotify/issues/7
  72
  73 [contributing]: https://github.com/fsnotify/fsnotify/blob/master/CONTRIBUTING.md
  74
  75 ## Related Projects
  76
  77 * [notify](https://github.com/rjeczalik/notify)
  78 * [fsevents](https://github.com/fsnotify/fsevents)
  79