listen 0.5.3 → 3.7.1

data/README.md

@@ -1,269 +1,400 @@
-# Listen [![Build Status](https://secure.travis-ci.org/guard/listen.png?branch=master)](http://travis-ci.org/guard/listen)
+# Listen
 
-The Listen gem listens to file modifications and notifies you about the changes.
+The `listen` gem listens to file modifications and notifies you about the changes.
+
+[![Development Status](https://github.com/guard/listen/workflows/Development/badge.svg)](https://github.com/guard/listen/actions?workflow=Development)
+[![Gem Version](https://badge.fury.io/rb/listen.svg)](http://badge.fury.io/rb/listen)
+[![Code Climate](https://codeclimate.com/github/guard/listen.svg)](https://codeclimate.com/github/guard/listen)
+[![Coverage Status](https://coveralls.io/repos/guard/listen/badge.svg?branch=master)](https://coveralls.io/r/guard/listen)
 
 ## Features
 
-* Works everywhere!
-* Supports watching multiple directories from a single listener.
-* OS-specific adapters for Mac OS X 10.6+, Linux and Windows.
-* Automatic fallback to polling if OS-specific adapter doesn't work.
+* OS-optimized adapters on MRI for Mac OS X 10.6+, Linux, \*BSD and Windows, [more info](#listen-adapters) below.
 * Detects file modification, addition and removal.
-* Checksum comparison for modifications made under the same second.
-* Allows supplying regexp-patterns to ignore and filter paths for better results.
-* Tested on all Ruby environments via [travis-ci](http://travis-ci.org/guard/listen).
+* You can watch multiple directories.
+* Regexp-patterns for ignoring paths for more accuracy and speed
+* Increased change detection accuracy on OS X HFS and VFAT volumes.
+* Continuous Integration: tested on selected Ruby environments via [Github Workflows](https:///github.com/guard/listen/master/.github/workflows).
+
+## Issues / limitations
+
+* Limited support for symlinked directories ([#279](https://github.com/guard/listen/issues/279)):
+  * Symlinks are always followed ([#25](https://github.com/guard/listen/issues/25)).
+  * Symlinked directories pointing within a watched directory are not supported ([#273](https://github.com/guard/listen/pull/273).
+* No directory/adapter-specific configuration options.
+* Support for plugins planned for future.
+* TCP functionality was removed in `listen` [3.0.0](https://github.com/guard/listen/releases/tag/v3.0.0) ([#319](https://github.com/guard/listen/issues/319), [#218](https://github.com/guard/listen/issues/218)). There are plans to extract this feature to separate gems ([#258](https://github.com/guard/listen/issues/258)), until this is finished, you can use by locking the `listen` gem to version `'~> 2.10'`.
+* Some filesystems won't work without polling (VM/Vagrant Shared folders, NFS, Samba, sshfs, etc.).
+* Windows and \*BSD adapter aren't continuously and automatically tested.
+* OSX adapter has some performance limitations ([#342](https://github.com/guard/listen/issues/342)).
+* Listeners do not notify across forked processes, if you wish for multiple processes to receive change notifications you must [listen inside of each process](https://github.com/guard/listen/issues/398#issuecomment-223957952).
+
+Pull requests or help is very welcome for these.
 
 ## Install
 
-``` bash
-gem install listen
+The simplest way to install `listen` is to use [Bundler](http://bundler.io).
+
+```ruby
+gem 'listen'
 ```
 
-## Usage
+## Complete Example
+Here is a complete example of using the `listen` gem:
+```ruby
+require 'listen'
+
+listener = Listen.to('/srv/app') do |modified, added, removed|
+  puts(modified: modified, added: added, removed: removed)
+end
+listener.start
+sleep
+```
+Running the above in the background, you can see the callback block being called in response to each command:
+```
+$ cd /srv/app
+$ touch a.txt
+{:modified=>[], :added=>["/srv/app/a.txt"], :removed=>[]}
+
+$ echo more >> a.txt
+{:modified=>["/srv/app/a.txt"], :added=>[], :removed=>[]}
 
-There are **two ways** to use Listen:
+$ mv a.txt b.txt
+{:modified=>[], :added=>["/srv/app/b.txt"], :removed=>["/srv/app/a.txt"]}
 
-1. Call `Listen.to` with either a single directory or multiple directories, then define the `change` callback in a block.
-2. Create a `listener` object and use it in an (ARel style) chainable way.
+$ vi b.txt
+# add a line to this new file and press ZZ to save and exit
+{:modified=>["/srv/app/b.txt"], :added=>[], :removed=>[]}
 
-Feel free to give your feeback via [Listen issues](https://github.com/guard/listen/issues)
+$ vi c.txt
+# add a line and press ZZ to save and exit
+{:modified=>[], :added=>["/srv/app/c.txt"], :removed=>[]}
 
-### Block API
+$ rm b.txt c.txt
+{:modified=>[], :added=>[], :removed=>["/srv/app/b.txt", "/srv/app/c.txt"]}
+```
+
+## Usage
+
+Call `Listen.to` with one or more directories and the "changes" callback passed as a block.
 
 ``` ruby
-# Listen to a single directory.
-Listen.to('dir/path/to/listen', :filter => /\.rb$/, :ignore => %r{ignored/path/}) do |modified, added, removed|
-  # ...
+listener = Listen.to('dir/to/listen', 'dir/to/listen2') do |modified, added, removed|
+  puts "modified absolute path array: #{modified}"
+  puts "added absolute path array: #{added}"
+  puts "removed absolute path array: #{removed}"
 end
+listener.start # starts a listener thread--does not block
 
-# Listen to multiple directories.
-Listen.to('dir/to/awesome_app', 'dir/to/other_app', :filter => /\.rb$/, :latency => 0.1) do |modified, added, removed|
-  # ...
-end
+# do whatever you want here...just don't exit the process :)
+
+sleep
 ```
+## Changes Callback
+
+Changes to the listened-to directories are reported by the listener thread in a callback.
+The callback receives **three** array parameters: `modified`, `added` and `removed`, in that order.
+Each of these three is always an array with 0 or more entries.
+Each array entry is an absolute path.
+
+### Pause / start / stop
 
-### "Object" API
+Listeners can also be easily paused and later un-paused with start:
 
 ``` ruby
-listener = Listen.to('dir/path/to/listen')
-listener = listener.ignore(%r{^ignored/path/})
-listener = listener.filter(/\.rb$/)
-listener = listener.latency(0.5)
-listener = listener.force_polling(true)
-listener = listener.polling_fallback_message(false)
-listener = listener.change(&callback)
-listener.start # blocks execution!
+listener = Listen.to('dir/path/to/listen') { |modified, added, removed| puts 'handle changes here...' }
+
+listener.start
+listener.paused?     # => false
+listener.processing? # => true
+
+listener.pause       # stops processing changes (but keeps on collecting them)
+listener.paused?     # => true
+listener.processing? # => false
+
+listener.start       # resumes processing changes
+listener.stop        # stop both listening to changes and processing them
 ```
 
-### Chainable
+  Note: While paused, `listen` keeps on collecting changes in the background - to clear them, call `stop`.
+
+  Note: You should keep track of all started listeners and `stop` them properly on finish.
+
+### Ignore / ignore!
+
+`Listen` ignores some directories and extensions by default (See DEFAULT_IGNORED_FILES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer).
+You can add ignoring patterns with the `ignore` option/method or overwrite default with `ignore!` option/method.
 
 ``` ruby
-Listen.to('dir/path/to/listen')
-      .ignore(%r{^ignored/path/})
-      .filter(/\.rb$/)
-      .latency(0.5)
-      .force_polling(true)
-      .polling_fallback_message('custom message')
-      .change(&callback)
-      .start # blocks execution!
+listener = Listen.to('dir/path/to/listen', ignore: /\.txt/) { |modified, added, removed| # ... }
+listener.start
+listener.ignore! /\.pkg/ # overwrite all patterns and only ignore pkg extension.
+listener.ignore /\.rb/   # ignore rb extension in addition of pkg.
+sleep
 ```
 
-### Pause/Unpause
+Note: `:ignore` regexp patterns are evaluated against relative paths.
+
+Note: Ignoring paths does not improve performance, except when Polling ([#274](https://github.com/guard/listen/issues/274)).
 
-Listener can also easily be paused/unpaused:
+### Only
+
+`Listen` watches all files (less the ignored ones) by default. If you want to only listen to a specific type of file (i.e., just `.rb` extension), you should use the `only` option/method.
 
 ``` ruby
-listener = Listen.to('dir/path/to/listen')
-listener.start(false) # non-blocking mode
-listener.pause   # stop listening to changes
-listener.paused? # => true
-listener.unpause
-listener.stop
+listener = Listen.to('dir/path/to/listen', only: /\.rb$/) { |modified, added, removed| # ... }
+listener.start
+listener.only /_spec\.rb$/ # overwrite all existing only patterns.
+sleep
 ```
 
-## Listening to changes on multiple directories
+Note: `:only` regexp patterns are evaluated only against relative **file** paths.
+
 
-The Listen gem provides the `MultiListener` class to watch multiple directories and
-handle their changes from a single listener:
+## Options
+
+All the following options can be set through the `Listen.to` after the directory path(s) params.
 
 ```ruby
-listener = Listen::MultiListener.new('app/css', 'app/js')
-listener.latency(0.5)
+ignore: [%r{/foo/bar}, /\.pid$/, /\.coffee$/]   # Ignore a list of paths
+                                                # default: See DEFAULT_IGNORED_FILES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer
 
-# Configure the listener to your needs...
+ignore!: %r{/foo/bar}                           # Same as ignore options, but overwrite default ignored paths.
 
-listener.start # blocks execution!
-````
+only: %r{.rb$}                                  # Only listen to specific files
+                                                # default: none
 
-For an easier access, the `Listen.to` method can also be used to create a multi-listener:
+latency: 0.5                                    # Set the delay (**in seconds**) between checking for changes
+                                                # default: 0.25 sec (1.0 sec for polling)
 
-``` ruby
-listener = Listen.to('app/css', 'app/js')
-                 .ignore(%r{^vendor/}) # both js/vendor and css/vendor will be ignored
-                 .change(&assets_callback)
+wait_for_delay: 4                               # Set the delay (**in seconds**) between calls to the callback when changes exist
+                                                # default: 0.10 sec
 
-listener.start # blocks execution!
+force_polling: true                             # Force the use of the polling adapter
+                                                # default: none
+
+relative: false                                 # Whether changes should be relative to current dir or not
+                                                # default: false
+
+polling_fallback_message: 'custom message'      # Set a custom polling fallback message (or disable it with false)
+                                                # default: "Listen will be polling for changes. Learn more at https://github.com/guard/listen#listen-adapters."
 ```
 
-## Changes callback
+## Logging and Debugging
 
-Changes to the listened-to directories gets reported back to the user in a callback.
-The registered callback gets invoked, when there are changes, with **three** parameters:
-`modified_paths`, `added_paths` and `removed_paths` in that particular order.
+`Listen` logs its activity to `Listen.logger`.
+This is the primary method of debugging.
 
-You can register a callback in two ways. The first way is by passing a block when calling
-the `Listen.to` method or when initializing a listener object:
+### Custom Logger
+You can call `Listen.logger =` to set a custom `listen` logger for the process. For example:
+```
+Listen.logger = Rails.logger
+```
 
-```ruby
-Listen.to('path/to/app') do |modified, added, removed|
-  # This block will be called when there are changes.
-end
+### Default Logger
+If no custom logger is set, a default `listen` logger which logs to to `STDERR` will be created and assigned to `Listen.logger`.
 
-# or ...
+The default logger defaults to the `error` logging level (severity).
+You can override the logging level by setting the environment variable `LISTEN_GEM_DEBUGGING=<level>`.
+For `<level>`, all standard `::Logger` levels are supported, with any mix of upper-/lower-case:
+```
+export LISTEN_GEM_DEBUGGING=debug # or 2 [deprecated]
+export LISTEN_GEM_DEBUGGING=info  # or 1 or true or yes [deprecated]
+export LISTEN_GEM_DEBUGGING=warn
+export LISTEN_GEM_DEBUGGING=fatal
+export LISTEN_GEM_DEBUGGING=error
+```
+The default of `error` will be used if an unsupported value is set.
 
-listener = Listen::Listener.new('path/to/app') do |modified, added, removed|
-  # This block will be called when there are changes.
-end
+Note: The alternate values `1`, `2`, `true` and `yes` shown above are deprecated and will be removed from `listen` v4.0.
 
+### Disabling Logging
+If you want to disable `listen` logging, set
+```
+Listen.logger = ::Logger.new('/dev/null')
 ```
+## Listen Adapters
 
-The second way to register a callback is be calling the `change` method on any
-listener passing it a block:
+The `Listen` gem has a set of adapters to notify it when there are changes.
 
-```ruby
-# Create a callback
-callback = Proc.new do |modified, added, removed|
-  # This proc will be called when there are changes.
-end
+There are 4 OS-specific adapters to support Darwin, Linux, \*BSD and Windows.
+These adapters are fast as they use some system-calls to implement the notifying function.
 
-listener = Listen.to('dir')
-listener.change(&callback) # convert the callback to a block and register it
+There is also a polling adapter - although it's much slower than other adapters,
+it works on every platform/system and scenario (including network filesystems such as VM shared folders).
 
-listener.start # blocks execution
-```
+The Darwin and Linux adapters are dependencies of the `listen` gem so they work out of the box. For other adapters a specific gem will have to be added to your Gemfile, please read below.
+
+The `listen` gem will choose the best adapter automatically, if present. If you
+want to force the use of the polling adapter, use the `:force_polling` option
+while initializing the listener.
+
+### On Windows
 
-### Paths in callbacks
+If you are on Windows, it's recommended to use the [`wdm`](https://github.com/Maher4Ever/wdm) adapter instead of polling.
 
-Listeners invoke callbacks passing them absolute paths by default:
+Please add the following to your Gemfile:
 
 ```ruby
-# Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
-# the listener.
-Listen.to('/home/user/app/css') do |modified, added, removed|
-  modified.inspect # => ['/home/user/app/css/style.css']
-end
+gem 'wdm', '>= 0.1.0', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
 ```
 
-#### Relative paths in callbacks
+### On \*BSD
+
+If you are on \*BSD you can try to use the [`rb-kqueue`](https://github.com/mat813/rb-kqueue) adapter instead of polling.
 
-When creating a listener for a **single** path (more specifically a `Listen::Listener` instance),
-you can pass `:relative_paths => true` as an option to get relative paths in
-your callback:
+Please add the following to your Gemfile:
 
 ```ruby
-# Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
-# the listener.
-Listen.to('/home/user/app/css', :relative_paths => true) do |modified, added, removed|
-  modified.inspect # => ['style.css']
+require 'rbconfig'
+if RbConfig::CONFIG['target_os'] =~ /bsd|dragonfly/i
+  gem 'rb-kqueue', '>= 0.2'
 end
+
 ```
 
-Passing the `:relative_paths => true` option won't work when listeneing to multiple
-directories:
+### Getting the [polling fallback message](#options)?
 
-```ruby
-# Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
-# the listener.
-Listen.to('/home/user/app/css', '/home/user/app/js', :relative_paths => true) do |modified, added, removed|
-  modified.inspect # => ['/home/user/app/css/style.css']
-end
+If you see:
+```
+Listen will be polling for changes.
 ```
 
-## Options
+This means the Listen gem can’t find an optimized adapter. Typically this is caused by:
 
-These options can be set through `Listen.to` params or via methods (see the "Object" API)
+- You’re on Windows and WDM gem isn’t installed.
+- You’re running the app without Bundler or RubyGems.
+- Using Sass which includes an ancient (the “dinosaur” type of ancient) version of the Listen gem.
 
-```ruby
-:filter => /\.rb$/, /\.coffee$/                # Filter files to listen to via a regexps list.
-                                               # default: none
+Possible solutions:
 
-:ignore => %r{app/CMake/}, /\.pid$/            # Ignore a list of paths (root directory or sub-dir)
-                                               # default: See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::DirectoryRecord
+1. Suppress the message by using the :force_polling option. Or, you could just ignore the message since it’s harmless.
+2. Windows users: Install the WDM gem.
+3. Upgrade Ruby (use RubyInstaller for Windows or RVM/rbenv for Mac) and RubyGems.
+3. Run your apps using Bundler.
+4. Sass users: Install the latest version of Listen and try again.
 
-:latency => 0.5                                # Set the delay (**in seconds**) between checking for changes
-                                               # default: 0.25 sec (1.0 sec for polling)
-
-:relative_paths => true                        # Enable the use of relative paths in the callback.
-                                               # default: false
+#### Simplified Bundler and Sass example
+Create a Gemfile with these lines:
+```
+source 'https://rubygems.org'
+gem 'listen'
+gem 'sass'
+```
+Next, use Bundler to update gems:
+```
+$ bundle update
+$ bundle exec sass --watch # ... or whatever app is using Listen.
+```
 
-:force_polling => true                         # Force the use of the polling adapter
-                                               # default: none
+### Increasing the amount of inotify watchers
 
-:polling_fallback_message => 'custom message'  # Set a custom polling fallback message (or disable it with `false`)
-                                               # default: "WARNING: Listen fallen back to polling, learn more at https://github.com/guard/listen#fallback."
+If you are running Debian, RedHat, or another similar Linux distribution, run the following in a terminal:
+```
+$ sudo sh -c "echo fs.inotify.max_user_watches=524288 >> /etc/sysctl.conf"
+$ sudo sysctl -p
+```
+If you are running ArchLinux, search the `/etc/sysctl.d/` directory for config files with the setting:
+```
+$ grep -H -s "fs.inotify.max_user_watches" /etc/sysctl.d/*
+/etc/sysctl.d/40-max_user_watches.conf:fs.inotify.max_user_watches=100000
+```
+Then change the setting in the file you found above to a higher value (see [here](https://www.archlinux.org/news/deprecation-of-etcsysctlconf/) for why):
+```
+$ sudo sh -c "echo fs.inotify.max_user_watches=524288 > /etc/sysctl.d/40-max-user-watches.conf"
+$ sudo sysctl --system
 ```
 
-### The patterns for filtering and ignoring paths
+#### The technical details
+Listen uses `inotify` by default on Linux to monitor directories for changes.
+It's not uncommon to encounter a system limit on the number of files you can monitor.
+For example, Ubuntu Lucid's (64bit) `inotify` limit is set to 8192.
 
-Just like the unix convention of beginning absolute paths with the
-directory-separator (forward slash `/` in unix) and with no prefix for relative paths,
-Listen doesn't prefix relative paths (to the watched directory) with a directory-separator.
+You can get your current inotify file watch limit by executing:
+```
+$ cat /proc/sys/fs/inotify/max_user_watches
+```
+When this limit is not enough to monitor all files inside a directory, the limit must be increased for Listen to work properly.
 
-Therefore make sure _NOT_ to prefix your regexp-patterns for filtering or ignoring paths
-with a directory-separator, otherwise they won't work as expected.
+You can set a new limit temporarily with:
+```
+$ sudo sysctl fs.inotify.max_user_watches=524288
+$ sudo sysctl -p
+```
+If you like to make your limit permanent, use:
+```
+$ sudo sh -c "echo fs.inotify.max_user_watches=524288 >> /etc/sysctl.conf"
+$ sudo sysctl -p
+```
+You may also need to pay attention to the values of `max_queued_events` and `max_user_instances` if Listen keeps on complaining.
 
-As an example: to ignore the `build` directory in a C-project, use `%r{build/}`
-and not `%r{/build/}`.
+#### More info
+Man page for [inotify(7)](https://linux.die.net/man/7/inotify).
+Blog post: [limit of inotify](https://blog.sorah.jp/2012/01/24/inotify-limitation).
 
-### Non-blocking listening to changes
+### Issues and Troubleshooting
 
-Starting a listener blocks the current thread by default. That means any code after the
-`start` call won't be run until the listener is stopped (which needs to be done from another thread).
+If the gem doesn't work as expected, start by setting `LISTEN_GEM_DEBUGGING=debug` or `LISTEN_GEM_DEBUGGING=info` as described above in [Logging and Debugging](#logging-and-debugging).
 
-For advanced usage there is an option to disable this behavior and have the listener start working
-in the background without blocking. To enable non-blocking listening the `start` method of
-the listener (be it `Listener` or `MultiListener`) needs to be called with `false` as a parameter.
+*NOTE: without providing the output after setting the `LISTEN_GEM_DEBUGGING=debug` environment variable, it is usually impossible to guess why `listen` is not working as expected.*
 
-Here is an example of using a listener in the non-blocking mode:
+#### 3 steps before you start diagnosing problems
+These 3 steps will:
 
-```ruby
-listener = Listen.to('dir/path/to/listen')
-listener.start(false) # doesn't block execution
+- help quickly troubleshoot obscure problems (trust me, most of them are obscure)
+- help quickly identify the area of the problem (a full list is below)
+- help you get familiar with listen's diagnostic mode (it really comes in handy, trust me)
+- help you create relevant output before you submit an issue (so we can respond with answers instead of tons of questions)
 
-# Code here will run immediately after starting the listener
+Step 1 - The most important option in Listen
+For effective troubleshooting set the `LISTEN_GEM_DEBUGGING=info` variable before starting `listen`.
 
-```
+Step 2 - Verify polling works
+Polling has to work ... or something is really wrong (and we need to know that before anything else).
 
-**note**: Using the `Listen.to` helper-method with a callback-block will always
-block execution. See the "Block API" section for an example.
+(see force_polling option).
 
-## Listen adapters
+After starting `listen`, you should see something like:
+```
+INFO -- : Record.build(): 0.06773114204406738 seconds
+```
+Step 3 - Trigger some changes directly without using editors or apps
+Make changes e.g. touch foo or echo "a" >> foo (for troubleshooting, avoid using an editor which could generate too many misleading events).
 
-The Listen gem has a set of adapters to notify it when there are changes.
-There are 3 OS-specific adapters to support Mac, Linux and Windows. These adapters are fast
-as they use some system-calls to implement the notifying function.
+You should see something like:
+```
+INFO -- : listen: raw changes: [[:added, "/home/me/foo"]]
+INFO -- : listen: final changes: {:modified=>[], :added=>["/home/me/foo"], :removed=>[]}
+```
+"raw changes" contains changes collected during the :wait_for_delay and :latency intervals, while "final changes" is what listen decided are relevant changes (for better editor support).
 
-There is also a polling adapter which is a cross-platform adapter and it will
-work on any system. This adapter is unfortunately slower than the rest of the adapters.
+## Performance
 
-The Listen gem will choose the best and working adapter for your machine automatically. If you
-want to force the use of the polling adapter, either use the `:force_polling` option
-while initializing the listener or call the `force_polling` method on your listener
-before starting it.
+If `listen` seems slow or unresponsive, make sure you're not using the Polling adapter (you should see a warning upon startup if you are).
 
-## Polling fallback
+Also, if the directories you're watching contain many files, make sure you're:
 
-When a OS-specific adapter doesn't work the Listen gem automatically falls back to the polling adapter.
-Here are some things you could try to avoid the polling fallback:
+* not using Polling (ideally)
+* using `:ignore` and `:only` options to avoid tracking directories you don't care about (important with Polling and on MacOS)
+* running `listen` with the `:latency` and `:wait_for_delay` options not too small or too big (depends on needs)
+* not watching directories with log files, database files or other frequently changing files
+* not using a version of `listen` prior to 2.7.7
+* not getting silent crashes within `listen` (see `LISTEN_GEM_DEBUGGING=debug`)
+* not running multiple instances of `listen` in the background
+* using a file system with atime modification disabled (ideally)
+* not using a filesystem with inaccurate file modification times (ideally), e.g. HFS, VFAT
+* not buffering to a slow terminal (e.g. transparency + fancy font + slow gfx card + lots of output)
+* ideally not running a slow encryption stack, e.g. btrfs + ecryptfs
 
-* [Update your Dropbox client](http://www.dropbox.com/downloading) (if used).
-* Increase latency. (Please [open an issue](https://github.com/guard/listen/issues/new) if you think that default is too low.)
-* Move or rename the listened folder.
-* Update/reboot your OS.
+When in doubt, `LISTEN_GEM_DEBUGGING=debug` can help discover the actual events and time they happened.
 
-If your application keeps using the polling-adapter and you can't figure out why, feel free to [open an issue](https://github.com/guard/listen/issues/new) (and be sure to give all the details).
+## Tips and Techniques
+- Watch only directories you're interested in.
+- Set your editor to save quickly (e.g. without backup files, without atomic-save)
+- Tweak the `:latency` and `:wait_for_delay` options until you get good results (see [options](#options)).
+- Add `:ignore` rules to silence all events you don't care about (reduces a lot of noise, especially if you use it on directories)
 
-## Development [![Dependency Status](https://gemnasium.com/guard/listen.png?branch=master)](https://gemnasium.com/guard/listen)
+## Development
 
 * Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/listen/master/frames).
 * Source hosted at [GitHub](https://github.com/guard/listen).
@@ -271,41 +402,61 @@ If your application keeps using the polling-adapter and you can't figure out why
 Pull requests are very welcome! Please try to follow these simple rules if applicable:
 
 * Please create a topic branch for every separate change you make.
-* Make sure your patches are well tested. All specs run with `rake spec:portability` must pass.
+* Make sure your patches are well tested. All specs must pass on [Travis CI](https://travis-ci.org/guard/listen).
 * Update the [Yard](http://yardoc.org/) documentation.
-* Update the README.
-* Update the CHANGELOG for noteworthy changes.
+* Update the [README](https://github.com/guard/listen/blob/master/README.md).
 * Please **do not change** the version number.
 
 For questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
 `#guard` (irc.freenode.net).
 
-## Acknowledgment
+## Releasing
+
+### Prerequisites
+
+* You must have commit rights to the GitHub repository.
+* You must have push rights for rubygems.org.
+
+### How to release
+
+1. Run `bundle install` to make sure that you have all the gems necessary for testing and releasing.
+2.  **Ensure all tests are passing by running `bundle exec rake`.**
+3. Determine which would be the correct next version number according to [semver](http://semver.org/).
+4. Update the version in `./lib/listen/version.rb`.
+5. Update the version in the Install section of `./README.md` (`gem 'listen', '~> X.Y'`).
+6. Commit the version in a single commit, the message should be "Preparing vX.Y.Z"
+7. Run `bundle exec rake release:full`; this will tag, push to GitHub, and publish to rubygems.org.
+8. Update and publish the release notes on the [GitHub releases page](https://github.com/guard/listen/releases) if necessary
+
+## Acknowledgments
 
 * [Michael Kessler (netzpirat)][] for having written the [initial specs](https://github.com/guard/listen/commit/1e457b13b1bb8a25d2240428ce5ed488bafbed1f).
 * [Travis Tilley (ttilley)][] for this awesome work on [fssm][] & [rb-fsevent][].
-* [Nathan Weizenbaum (nex3)][] for [rb-inotify][], a thorough inotify wrapper.
-* [stereobooster][] for [rb-fchange][], windows support wouldn't exist without him.
+* [Natalie Weizenbaum (nex3)][] for [rb-inotify][], a thorough inotify wrapper.
+* [Mathieu Arnold (mat813)][] for [rb-kqueue][], a simple kqueue wrapper.
+* [Maher Sallam][] for [wdm][], windows support wouldn't exist without him.
 * [Yehuda Katz (wycats)][] for [vigilo][], that has been a great source of inspiration.
 
-## Authors
+## Author
 
-* [Thibaud Guillaume-Gentil][] ([@thibaudgg](http://twitter.com/thibaudgg))
-* [Maher Sallam][] ([@mahersalam](http://twitter.com/mahersalam))
+[Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](https://twitter.com/thibaudgg))
 
 ## Contributors
 
-[https://github.com/guard/listen/contributors](https://github.com/guard/listen/contributors)
+[https://github.com/guard/listen/graphs/contributors](https://github.com/guard/listen/graphs/contributors)
 
-[Thibaud Guillaume-Gentil]: https://github.com/thibaudgg
+[Thibaud Guillaume-Gentil (thibaudgg)]: https://github.com/thibaudgg
 [Maher Sallam]: https://github.com/Maher4Ever
 [Michael Kessler (netzpirat)]: https://github.com/netzpirat
 [Travis Tilley (ttilley)]: https://github.com/ttilley
 [fssm]: https://github.com/ttilley/fssm
 [rb-fsevent]: https://github.com/thibaudgg/rb-fsevent
-[Nathan Weizenbaum (nex3)]: https://github.com/nex3
+[Mathieu Arnold (mat813)]: https://github.com/mat813
+[Natalie Weizenbaum (nex3)]: https://github.com/nex3
 [rb-inotify]: https://github.com/nex3/rb-inotify
 [stereobooster]: https://github.com/stereobooster
 [rb-fchange]: https://github.com/stereobooster/rb-fchange
+[rb-kqueue]: https://github.com/mat813/rb-kqueue
 [Yehuda Katz (wycats)]: https://github.com/wycats
 [vigilo]: https://github.com/wycats/vigilo
+[wdm]: https://github.com/Maher4Ever/wdm