author | Mikael Berthe <mikael@lilotux.net> |
Sat, 29 Sep 2018 18:09:54 +0200 | |
changeset 242 | 2a9ec03fe5a1 |
child 256 | 6d9efbef00a9 |
permissions | -rw-r--r-- |
242
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
1 |
# File system notifications for Go |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
2 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
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) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
4 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
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: |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
6 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
7 |
```console |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
8 |
go get -u golang.org/x/sys/... |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
9 |
``` |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
10 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
11 |
Cross platform: Windows, Linux, BSD and macOS. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
12 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
13 |
|Adapter |OS |Status | |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
14 |
|----------|----------|----------| |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
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)| |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
16 |
|kqueue |BSD, macOS, iOS\*|Supported [![Build Status](https://travis-ci.org/fsnotify/fsnotify.svg?branch=master)](https://travis-ci.org/fsnotify/fsnotify)| |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
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)| |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
18 |
|FSEvents |macOS |[Planned](https://github.com/fsnotify/fsnotify/issues/11)| |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
19 |
|FEN |Solaris 11 |[In Progress](https://github.com/fsnotify/fsnotify/issues/12)| |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
20 |
|fanotify |Linux 2.6.37+ | | |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
21 |
|USN Journals |Windows |[Maybe](https://github.com/fsnotify/fsnotify/issues/53)| |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
22 |
|Polling |*All* |[Maybe](https://github.com/fsnotify/fsnotify/issues/9)| |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
23 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
24 |
\* Android and iOS are untested. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
25 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
26 |
Please see [the documentation](https://godoc.org/github.com/fsnotify/fsnotify) and consult the [FAQ](#faq) for usage information. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
27 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
28 |
## API stability |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
29 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
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). |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
31 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
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. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
33 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
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`. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
35 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
36 |
## Contributing |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
37 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
38 |
Please refer to [CONTRIBUTING][] before opening an issue or pull request. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
39 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
40 |
## Example |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
41 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
42 |
See [example_test.go](https://github.com/fsnotify/fsnotify/blob/master/example_test.go). |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
43 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
44 |
## FAQ |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
45 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
46 |
**When a file is moved to another directory is it still being watched?** |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
47 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
48 |
No (it shouldn't be, unless you are watching where it was moved to). |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
49 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
50 |
**When I watch a directory, are all subdirectories watched as well?** |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
51 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
52 |
No, you must add watches for any directory you want to watch (a recursive watcher is on the roadmap [#18][]). |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
53 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
54 |
**Do I have to watch the Error and Event channels in a separate goroutine?** |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
55 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
56 |
As of now, yes. Looking into making this single-thread friendly (see [howeyc #7][#7]) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
57 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
58 |
**Why am I receiving multiple events for the same file on OS X?** |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
59 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
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][]). |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
61 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
62 |
**How many files can be watched at once?** |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
63 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
64 |
There are OS-specific limits as to how many watches can be created: |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
65 |
* Linux: /proc/sys/fs/inotify/max_user_watches contains the limit, reaching this limit results in a "no space left on device" error. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
66 |
* BSD / OSX: sysctl variables "kern.maxfiles" and "kern.maxfilesperproc", reaching these limits results in a "too many open files" error. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
67 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
68 |
[#62]: https://github.com/howeyc/fsnotify/issues/62 |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
69 |
[#18]: https://github.com/fsnotify/fsnotify/issues/18 |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
70 |
[#11]: https://github.com/fsnotify/fsnotify/issues/11 |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
71 |
[#7]: https://github.com/howeyc/fsnotify/issues/7 |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
72 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
73 |
[contributing]: https://github.com/fsnotify/fsnotify/blob/master/CONTRIBUTING.md |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
74 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
75 |
## Related Projects |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
76 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
77 |
* [notify](https://github.com/rjeczalik/notify) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
78 |
* [fsevents](https://github.com/fsnotify/fsevents) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
79 |