listen 1.3.1 → 2.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d9b4d00e44252c4d2c28d7b1d1032789dda96247
-  data.tar.gz: 3040790b24b6f3020fdf68b3f86eaf9bdffc0f7b
+  metadata.gz: e5eb3d853fcddc242d96e4e0295b3966b6349119
+  data.tar.gz: aa33f0a0e2d623d76027f758b78463ae2c052573
 SHA512:
-  metadata.gz: 19395a1831d03b0f76627e4343d0baa9611a2a7f2a89b5d28aaeadae555cdb6a3518a6f7e9be2fb6dcc0d3e4ab8d6c804742ee529f65c8a756ff30507e3f1ded
-  data.tar.gz: fd612f0cb477281402c7b95cad3681f813be231b7b098d81bbfb5c7f92ae3fbf87b8f18b774047ef308b4ee0feb77644f2a61453315fced0387f8ea80d605b31
+  metadata.gz: ce58ba37a3bdee68cb69dcff3b3a583dec582cb1ccb680e81c6e14d33fea0d5a0d99fcf16e4346c91d56786d31f0e694c671c52de3eab4269e48409bfce3d3c5
+  data.tar.gz: 9e6856329957aeedb9415eaf26255b373ff60d288128bd82a2ca8cbd9c7e9fe075a74c055e0ddcb7afd6fc68d6781262c94d7bde8005e6b0a765834e1ce79ec0

data/CHANGELOG.md

@@ -1,368 +1 @@
-# !!! CHANGELOG moved to Github [releases](https://github.com/guard/listen/releases) page !!!
-
-
-## 1.2.2 - Jun 17, 2013
-
-### Bug fix
-
-- Rescue all error on sha1_checksum generation. ([@thibaudgg][])
-
-## 1.2.1 - Jun 11, 2013
-
-### Improvement
-
-- Ignore 'bundle' folder by default. ([@thibaudgg][])
-
-## 1.2.0 - Jun 11, 2013
-
-### Improvement
-
-- [#124][] New `force_adapter` option, skip the `.listen_test` adapter test. ([@nicobrevin][])
-
-## 1.1.6 - Jun 4, 2013
-
-### Change
-
-- [#120][] Warn when using relative_paths option when listening to multiple diretories. (reported by [@chriseppstein][], added by [@thibaudgg][])
-
-## 1.1.5 - Jun 3, 2013
-
-### Bug fix
-
-- [#122][] Fix stop called very soon after starting. (reported by [@chriseppstein][], fixed by [@thibaudgg][])
-
-## 1.1.4 - May 28, 2013
-
-### Bug fix
-
-- [#118][] Prevent polling just because the adapter gem was already required. ([@nilbus][])
-
-## 1.1.3 - May 21, 2013
-
-### Bug fix
-
-- [#117][] Fix jruby error on Pathname#relative_path_from. ([@luikore][])
-
-## 1.1.2 - May 14, 2013
-
-### Bug fix
-
-- [#115][] Fix for directory containing non-ascii chars. ([@luikore][])
-
-## 1.1.1 - May 14, 2013
-
-### Bug fix
-
-- [#113][] Kill poller_thread before waiting for it to die. ([@antifuchs][])
-
-## 1.1.0 - May 11, 2013
-
-### Bug fix
-
-- [#112][] Expand path for the given directories. (reported by [@nex3][], fixed by [@thibaudgg][])
-
-### Change
-
-- [#110][] Remove MultiListener deprecation warning message. (reported by [@nex3][], fixed by [@thibaudgg][])
-
-## 1.0.3 - April 29, 2013
-
-### Bug fix
-
-- Rescue Errno::EBADF on sha1_checksum generation. ([@thibaudgg][])
-
-## 1.0.2 - April 22, 2013
-
-### Bug fix
-
-- [#104][] Avoid conflict with ActiveSupport::Dependencies::Loadable. ([@nysalor][])
-
-## 1.0.1 - April 22, 2013
-
-### Bug fix
-
-- [#103][] Support old version of rubygems. (reported by [@ahoward][], fixed by [@thibaudgg][])
-
-## 1.0.0 - April 20, 2013
-
-### Bug fix
-
-- [#93][] Remove dependency operator in the "gem install" message. (reported by [@scottdavis][], fixed by [@rymai][])
-
-### Changes & deprecations
-
-- [#98][] `Listen.to` does not block the current thread anymore. Use `Listen.to!` if you want the old behavior back. ([@rymai][])
-- [#98][] `Listen::Listener#start` does not block the current thread anymore. Use `Listen::Listener#start!` if you want the old behavior back. ([@rymai][])
-- [#98][] `Listen::Listener#start`'s `blocking` parameter is deprecated. ([@rymai][])
-
-### Improvements
-
-- [#98][] New method: `Listen.to!` which blocks the current thread. ([@rymai][])
-- [#98][] New method: `Listen::Listener#start!` to start the listener and block the current thread. ([@martikaljuve][] & [@rymai][])
-- [#95][] Make `Listen::Listener` capable of listening to multiple directories, deprecates `Listen::MultiListener`, defaults `Listener#relative_paths` to `true` when listening to a single directory (see [#131][]). ([@rymai][])
-- [#85][] Compute the SHA1 sum only for regular files. ([@antifuchs][])
-- New methods: `Listen::Adapter#pause`, `Listen::Adapter#unpause` and `Listen::Adapter#paused?`. ([@rymai][])
-- Refactor `Listen::DirectoryRecord` internals. ([@rymai][])
-- Refactor `Listen::DependencyManager` internals. ([@rymai][])
-
-## 0.7.3 - February 24, 2013
-
-### Bug fixes
-
-- [#88][] Update wdm dependency. ([@mrbinky3000][])
-- [#78][] Depend on latest rb-inotify. ([@mbj][])
-
-## 0.7.2 - January 11, 2013
-
-### Bug fix
-
-- [#76][] Exception on filename which is not in UTF-8. ([@piotr-sokolowski][])
-
-## 0.7.1 - January 6, 2013
-
-### Bug fix
-
-- [#75][] Default high precision off if the mtime call fails. ([@zanker][])
-
-## 0.7.0 - December 29, 2012
-
-### Bug fix
-
-- [#73][] Rescue Errno::EOPNOTSUPP on sha1_checksum generation. ([@thibaudgg][])
-
-### New feature
-
-- [#72][] Add support for *BSD with rb-kqueue. ([@mat813][])
-
-## 0.6.0 - November 21, 2012
-
-### New feature
-
-- [#68][] Add bang versions for `Listener#filter` and `Listener#ignore` methods. ([@tarsolya][])
-
-## 0.5.3 - October 3, 2012
-
-### Bug fixes
-
-- [#65][] Fix ruby warning in adapter.rb. ([@vongruenigen][])
-- [#64][] ENXIO raised when hashing UNIX domain socket file. ([@sunaku][])
-
-## 0.5.2 - Septemper 23, 2012
-
-### Bug fix
-
-- [#62][] Fix double change callback with polling adapter. ([@thibaudgg][])
-
-## 0.5.1 - Septemper 18, 2012
-
-### Bug fix
-
-- [#61][] Fix a synchronisation bug that caused constant fallback to polling. ([@Maher4Ever][])
-
-## 0.5.0 - Septemper 1, 2012
-
-### New features
-
-- Add a dependency manager to handle platform-specific gems. So there is no need anymore to install
-  extra gems which will never be used on the user system. ([@Maher4Ever][])
-- Add a manual reporting mode to the adapters. ([@Maher4Ever][])
-
-### Improvements
-
-- [#28][] Enhance the speed of detecting changes on Windows by using the [WDM][] library. ([@Maher4Ever][])
-
-## 0.4.7 - June 27, 2012
-
-### Bug fixes
-
-- Increase latency to 0.25, to avoid useless polling fallback. ([@thibaudgg][])
-- Change watched inotify events, to avoid duplication callback. ([@thibaudgg][])
-- [#41][] Use lstat instead of stat when calculating mtime. ([@ebroder][])
-
-## 0.4.6 - June 20, 2012
-
-### Bug fix
-
-- [#39][] Fix digest race condition. ([@dkubb][])
-
-## 0.4.5 - June 13, 2012
-
-### Bug fix
-
-- [#39][] Rescue Errno::ENOENT when path inserted doesn't exist. (reported by [@textgoeshere][], fixed by [@thibaudgg][] and [@rymai][])
-
-## 0.4.4 - June 8, 2012
-
-### Bug fixes
-
-- ~~[#39][] Non-existing path insertion bug. (reported by [@textgoeshere][], fixed by [@thibaudgg][])~~
-- Fix relative path for directories containing special characters. (reported by [@napcs][], fixed by [@netzpirat][])
-
-## 0.4.3 - June 6, 2012
-
-### Bug fixes
-
-- [#24][] Fail gracefully when the inotify limit is not enough for Listen to function. (reported by [@daemonza][], fixed by [@Maher4Ever][])
-- [#32][] Fix a crash when trying to calculate the checksum of unreadable files. (reported by [@nex3][], fixed by [@Maher4Ever][])
-
-### Improvements
-
-- Add `Listener#relative_paths`. ([@Maher4Ever][])
-- Add `Adapter#started?`. ([@Maher4Ever][])
-- Dynamically detect the mtime precision used on a system. ([@Maher4Ever][] with help from [@nex3][])
-
-## 0.4.2 - May 1, 2012
-
-### Bug fixes
-
-- [#21][] Issues when listening to changes in relative paths. (reported by [@akerbos][], fixed by [@Maher4Ever][])
-- [#27][] Wrong reports for files modifications. (reported by [@cobychapple][], fixed by [@Maher4Ever][])
-- Fix segmentation fault when profiling on Windows. ([@Maher4Ever][])
-- Fix redundant watchers on Windows. ([@Maher4Ever][])
-
-### Improvements
-
-- [#17][] Use regexp-patterns with the `ignore` method instead of supplying paths. (reported by [@fny][], added by [@Maher4Ever][])
-- Speed improvement when listening to changes in directories with ignored paths. ([@Maher4Ever][])
-- Added `.rbx` and `.svn` to ignored directories. ([@Maher4Ever][])
-
-## 0.4.1 - April 15, 2012
-
-### Bug fix
-
-- [#18][] Listener crashes when removing directories with nested paths. (reported by [@daemonza][], fixed by [@Maher4Ever][])
-
-## 0.4.0 - April 9, 2012
-
-### New features
-
-- Add `Adapter#wait_for_callback`. ([@Maher4Ever][])
-- Add `Listen::MultiListener` class to listen to multiple directories at once. ([@Maher4Ever][])
-- Allow passing multiple directories to the `Listen.to` method. ([@Maher4Ever][])
-- Add `blocking` option to `Listen#start` which can be used to disable blocking the current thread upon starting. ([@Maher4Ever][])
-- Use absolute-paths in callbacks by default instead of relative-paths. ([@Maher4Ever][])
-- Add `relative_paths` option to `Listen::Listener` to retain the old functionality. ([@Maher4Ever][])
-
-### Improvements
-
-- Encapsulate thread spawning in the linux-adapter. ([@Maher4Ever][])
-- Encapsulate thread spawning in the darwin-adapter. ([@Maher4Ever][] with [@scottdavis][] help)
-- Encapsulate thread spawning in the windows-adapter. ([@Maher4Ever][])
-- Fix linux-adapter bug where Listen would report file-modification events on the parent-directory. ([@Maher4Ever][])
-
-### Change
-
-- Remove `wait_until_listening` as adapters doesn't need to run inside threads anymore ([@Maher4Ever][])
-
-## 0.3.3 - March 6, 2012
-
-### Improvement
-
-- Improve pause/unpause. ([@thibaudgg][])
-
-## 0.3.2 - March 4, 2012
-
-### New feature
-
-- Add pause/unpause listener's methods. ([@thibaudgg][])
-
-## 0.3.1 - February 22, 2012
-
-### Bug fix
-
-- [#9][] Ignore doesn't seem to work. (reported by [@markiz][], fixed by [@thibaudgg][])
-
-## 0.3.0 - February 21, 2012
-
-### New features
-
-- Add automatic fallback to polling if system adapter doesn't work (like a DropBox folder). ([@thibaudgg][])
-- Add latency and force_polling options. ([@Maher4Ever][])
-
-## 0.2.0 - February 13, 2012
-
-### New features
-
-- Add checksum comparaison support for detecting consecutive file modifications made during the same second. ([@thibaudgg][])
-- Add rb-fchange support. ([@thibaudgg][])
-- Add rb-inotify support. ([@thibaudgg][] with [@Maher4Ever][] help)
-- Add rb-fsevent support. ([@thibaudgg][])
-- Add non-recursive diff with multiple directories support. ([@thibaudgg][])
-- Ignore `.DS_Store` files by default. ([@thibaudgg][])
-
-## 0.1.0 - January 28, 2012
-
-- First version with only a polling adapter and basic features set (ignore & filter). ([@thibaudgg][])
-
-<!--- The following link definition list is generated by PimpMyChangelog --->
-[#9]: https://github.com/guard/listen/issues/9
-[#17]: https://github.com/guard/listen/issues/17
-[#18]: https://github.com/guard/listen/issues/18
-[#21]: https://github.com/guard/listen/issues/21
-[#24]: https://github.com/guard/listen/issues/24
-[#27]: https://github.com/guard/listen/issues/27
-[#28]: https://github.com/guard/listen/issues/28
-[#32]: https://github.com/guard/listen/issues/32
-[#39]: https://github.com/guard/listen/issues/39
-[#41]: https://github.com/guard/listen/issues/41
-[#61]: https://github.com/guard/listen/issues/61
-[#62]: https://github.com/guard/listen/issues/62
-[#64]: https://github.com/guard/listen/issues/64
-[#65]: https://github.com/guard/listen/issues/65
-[#68]: https://github.com/guard/listen/issues/68
-[#72]: https://github.com/guard/listen/issues/72
-[#73]: https://github.com/guard/listen/issues/73
-[#75]: https://github.com/guard/listen/issues/75
-[#76]: https://github.com/guard/listen/issues/76
-[#78]: https://github.com/guard/listen/issues/78
-[#85]: https://github.com/guard/listen/issues/85
-[#88]: https://github.com/guard/listen/issues/88
-[#93]: https://github.com/guard/listen/issues/93
-[#95]: https://github.com/guard/listen/issues/95
-[#96]: https://github.com/guard/listen/issues/96
-[#98]: https://github.com/guard/listen/issues/98
-[#103]: https://github.com/guard/listen/issues/103
-[#104]: https://github.com/guard/listen/issues/104
-[#110]: https://github.com/guard/listen/issues/110
-[#112]: https://github.com/guard/listen/issues/112
-[#113]: https://github.com/guard/listen/issues/113
-[#115]: https://github.com/guard/listen/issues/115
-[#117]: https://github.com/guard/listen/issues/117
-[#118]: https://github.com/guard/listen/issues/118
-[#120]: https://github.com/guard/listen/issues/120
-[#122]: https://github.com/guard/listen/issues/122
-[#124]: https://github.com/guard/listen/issues/124
-[#131]: https://github.com/guard/listen/issues/131
-[@21croissants]: https://github.com/21croissants
-[@Maher4Ever]: https://github.com/Maher4Ever
-[@ahoward]: https://github.com/ahoward
-[@akerbos]: https://github.com/akerbos
-[@antifuchs]: https://github.com/antifuchs
-[@chriseppstein]: https://github.com/chriseppstein
-[@cobychapple]: https://github.com/cobychapple
-[@daemonza]: https://github.com/daemonza
-[@dkubb]: https://github.com/dkubb
-[@ebroder]: https://github.com/ebroder
-[@fny]: https://github.com/fny
-[@luikore]: https://github.com/luikore
-[@markiz]: https://github.com/markiz
-[@martikaljuve]: https://github.com/martikaljuve
-[@mat813]: https://github.com/mat813
-[@mbj]: https://github.com/mbj
-[@mrbinky3000]: https://github.com/mrbinky3000
-[@napcs]: https://github.com/napcs
-[@netzpirat]: https://github.com/netzpirat
-[@nex3]: https://github.com/nex3
-[@nicobrevin]: https://github.com/nicobrevin
-[@nilbus]: https://github.com/nilbus
-[@nysalor]: https://github.com/nysalor
-[@piotr-sokolowski]: https://github.com/piotr-sokolowski
-[@rehevkor5]: https://github.com/rehevkor5
-[@rymai]: https://github.com/rymai
-[@scottdavis]: https://github.com/scottdavis
-[@sunaku]: https://github.com/sunaku
-[@tarsolya]: https://github.com/tarsolya
-[@textgoeshere]: https://github.com/textgoeshere
-[@thibaudgg]: https://github.com/thibaudgg
-[@vongruenigen]: https://github.com/vongruenigen
-[@zanker]: https://github.com/zanker
+# Moved to [Github releases](https://github.com/guard/listen/releases) page.

data/README.md

@@ -2,117 +2,64 @@
 
 The Listen gem listens to file modifications and notifies you about the changes.
 
+## WARNING
+
+Master branch is `v2.0.0.beta` version, use the [v1.3 branch](https://github.com/guard/listen/tree/v1.3) for the stable release.
+
+*BSD and Windows adapter are still a work in progress, any help is very welcome. Thanks!
+
 ## Features
 
-* Works everywhere!
 * Supports watching multiple directories from a single listener.
-* OS-specific adapters for Mac OS X 10.6+, Linux, *BSD and Windows.
-* Automatic fallback to polling if OS-specific adapter doesn't work.
+* OS-specific adapters on MRI for Mac OS X 10.6+, Linux, *BSD and Windows, [more info](#listen-adapters) bellow.
 * Detects file modification, addition and removal.
-* File content 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](https://travis-ci.org/guard/listen).
+* Allows supplying regexp-patterns to ignore paths for better results.
+* File content checksum comparison for modifications made under the same second (OS X only).
+* Tested on MRI Ruby environments (1.9+ only) via [Travis CI](https://travis-ci.org/guard/listen), JRuby and Rubinius should work with polling.
 
-## Pending features
+Please note that Windows and *BSD adapter aren't continuously and automaticaly tested.
 
-Still not implemented, pull requests are welcome.
+## Pending features
 
-* Symlinks support. [#25](https://github.com/guard/listen/issues/25)
-* Signal handling. [#105](https://github.com/guard/listen/issues/105)
 * Non-recursive directory scanning. [#111](https://github.com/guard/listen/issues/111)
+* Symlinks support. [#25](https://github.com/guard/listen/issues/25)
 
-## Install
-
-### Using Bundler
-
-The simplest way to install Listen is to use Bundler.
-
-Add Listen to your Gemfile:
-
-```ruby
-group :development do
-  gem 'listen'
-end
-```
-
-and install it by running Bundler:
+Pull request or help is very welcome for these.
 
-```bash
-$ bundle
-```
+## Changelog
 
-### Install the gem with RubyGems
+The Changelog is on now on the [Github releases](https://github.com/guard/listen/releases) section.
 
-```bash
-$ gem install listen
-```
+## Install
 
-### On Windows
-
-If your are on Windows and using Ruby MRI >= 1.9.2 you can try to use the [`wdm`](https://github.com/Maher4Ever/wdm) instead of polling.
-Please add the following to your Gemfile:
+The simplest way to install Listen is to use [Bundler](http://bundler.io).
 
 ```ruby
-require 'rbconfig'
-gem 'wdm', '>= 0.1.0' if RbConfig::CONFIG['target_os'] =~ /mswin|mingw/i
+  gem 'listen', '~> 2.0'
 ```
 
 ## Usage
 
-There are **two ways** to use Listen:
-
-1. Block API: Call `Listen.to`/`Listen.to!` with either a single directory or multiple directories, then define the `change` callback in a block.
-2. "Object" API: Create a `listener` object and use it in a chainable way.
-
-### Block API
+Call `Listen.to` with either a single directory or multiple directories, then define the "changes" callback in a block.
 
 ``` ruby
-# Listen to a single directory.
-Listen.to('dir/path/to/listen', :filter => /\.rb$/, :ignore => %r{ignored/path/}) do |modified, added, removed|
-  # ...
-end
-
-# Listen to multiple directories.
-Listen.to('dir/to/awesome_app', 'dir/to/other_app', :filter => /\.rb$/, :latency => 0.1) do |modified, added, removed|
-  # ...
+listener = Listen.to('dir/to/listen', 'dir/to/listen2') do |modified, added, removed|
+  puts "modified absolute path: #{modified}"
+  puts "added absolute path: #{added}"
+  puts "removed absolute path: #{removed}"
 end
+listener.start # not blocking
+sleep
 ```
 
-### "Object" API
-
-``` 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.force_adapter(Listen::Adapters::Linux)
-listener = listener.change(&callback)
-listener.start
-```
-
-**Note**: All the "Object" API methods except `start`/`start!` return the listener
-and are thus chainable:
-
-``` 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
-```
-
-### Pause/Unpause
+### Pause / unpause / stop
 
-Listener can also easily be paused/unpaused:
+Listener can also be easily paused/unpaused:
 
 ``` ruby
-listener = Listen.to('dir/path/to/listen')
-listener.start   # non-blocking mode
+listener = Listen.to('dir/path/to/listen') { |modified, added, removed| # ... }
+listener.start
+listener.listen? # => true
 listener.pause   # stop listening to changes
 listener.paused? # => true
 listener.unpause # start listening to changes again
@@ -123,178 +70,98 @@ listener.stop    # stop completely the listener
 
 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.
+`modified`, `added` and `removed` paths, in that particular order.
+Paths are always returned in their absolute form.
 
-You can register a callback in two ways. The first way is by passing a block when calling
-the `Listen.to`/`Listen.to!` method or when initializing a listener object:
+Example:
 
 ```ruby
-Listen.to('path/to/app') do |modified, added, removed|
+listener = Listen.to('path/to/app') do |modified, added, removed|
   # This block will be called when there are changes.
 end
-
-# or ...
-
-listener = Listen::Listener.new('path/to/app') do |modified, added, removed|
-  # This block will be called when there are changes.
-end
-
+listener.start
+sleep
 ```
 
-The second way to register a callback is by calling the `#change` method on a
-listener passing it a block:
+or ...
 
 ```ruby
 # Create a callback
 callback = Proc.new do |modified, added, removed|
   # This proc will be called when there are changes.
 end
-
-listener = Listen.to('dir')
-listener.change(&callback) # convert the callback to a block and register it
-
+listener = Listen.to('dir', &callback)
 listener.start
-```
-
-### Paths in callbacks
-
-Listeners invoke callbacks passing them absolute paths by default:
-
-```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
-```
-
-#### Relative paths in callbacks
-
-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:
-
-```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']
-end
-```
-
-Passing the `:relative_paths => true` option won't work when listening to multiple
-directories:
-
-```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
+sleep
 ```
 
 ## Options
 
-All the following options can be set through the `Listen.to`/`Listen.to!` params
-or via ["Object" API](#object-api) methods:
+All the following options can be set through the `Listen.to` after the directory path(s) params.
 
 ```ruby
-: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
+ignore: [%r{/foo/bar}, /\.pid$/, /\.coffee$/]   # Ignore a list of paths
+                                                # default: See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer
 
-:filter => /\.rb$/, /\.coffee$/               # Filter files to listen to via a regexps list.
-                                              # default: none
+ignore!: %r{/foo/bar}                           # Same as ignore options, but overwrite default ignored paths.
 
-:latency => 0.5                               # Set the delay (**in seconds**) between checking for changes
-                                              # default: 0.25 sec (1.0 sec for polling)
+latency: 0.5                                    # Set the delay (**in seconds**) between checking for changes
+                                                # default: 0.25 sec (1.0 sec for polling)
 
-:force_adapter => Listen::Adapters::Linux     # Force the use of a particular adapter class
-                                              # default: none
+force_polling: true                             # Force the use of the polling adapter
+                                                # default: none
 
-:force_polling => true                        # Force the use of the polling adapter
-                                              # default: none
+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#polling-fallback."
 
-: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#polling-fallback."
-
-:relative_paths => true                       # Enable the use of relative paths in the callback.
-                                              # default: false
+debug: true                                     # Enable Celluloid logger
+                                                # default: false
 ```
 
-### Note on the patterns for ignoring and filtering paths
-
-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.
-
-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.
+## Listen adapters
 
-As an example: to ignore the `build` directory in a C-project, use `%r{build/}`
-and not `%r{/build/}`.
+The Listen gem has a set of adapters to notify it when there are changes.
+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.
 
-Use `#filter!` and `#ignore!` methods to overwrites default patterns.
+There is also a polling adapter which is a cross-platform adapter and it will
+work on any system. This adapter is slower than the rest of the adapters.
 
-## Blocking listening to changes
+Darwin and Linux adapter are dependencies of the Listen gem so they work out of the box. For other adapters a specific gem need to be added to your Gemfile, please read bellow.
 
-Calling `Listen.to` with a block doesn't block the current thread. If you want
-to block the current thread instead until the listener is stopped (which needs
-to be done from another thread), you can use `Listen.to!`.
+The Listen gem choose the good adapter (if present) automatically. If you
+want to force the use of the polling adapter use the `:force_polling` option
+while initializing the listener.
 
-Similarly, if you're using the "Object" API, you can use `#start!` instead of `#start` to block the
-current thread until the listener is stopped.
+### On Windows
 
-Here is an example of using a listener in the blocking mode:
+If your are on Windows you can try to use the [`wdm`](https://github.com/Maher4Ever/wdm) instead of polling.
+Please add the following to your Gemfile:
 
 ```ruby
-Listen.to!('dir/path/to/listen') # block execution
-
-# Code here will not run until the listener is stopped
-
+require 'rbconfig'
+gem 'wdm', '>= 0.1.0' if RbConfig::CONFIG['target_os'] =~ /mswin|mingw|cygwin/i
 ```
 
-Here is an example of using a listener started with the "Object" API in blocking mode:
-
-```ruby
-listener = Listen.to('dir/path/to/listen')
-listener.start! # block execution
+### On *BSD
 
-# Code here will not run until the listener is stopped
+If your are on *BSD you can try to use the [`rb-kqueue`](https://github.com/mat813/rb-kqueue) instead of polling.
+Please add the following to your Gemfile:
 
+```ruby
+require 'rbconfig'
+gem 'rb-kqueue', '>= 0.2' if RbConfig::CONFIG['target_os'] =~ /freebsd/i
 ```
 
-**Note**: Using the `Listen.to!` helper-method with or without a callback-block
-will always start the listener right away and block execution of the current thread.
-
-## Listen adapters
-
-The Listen gem has a set of adapters to notify it when there are changes.
-There are 4 OS-specific adapters to support Mac, Linux, *BSD and Windows.
-These adapters are fast as they use some system-calls to implement the notifying function.
-
-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.
-
-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.
-
-It is also possible to force the use of a particular adapter, by using the `:force_adapter`
-option.  This option skips the usual adapter choosing mechanism and uses the given
-adapter class instead.  The adapter choosing mechanism requires write permission
-to your watched directories and will needlessly load code, which isn't always desirable.
-
-## Polling fallback
+### Issues
 
-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:
+Sometimes OS-specific adapter doesn't work, :'(
+Here are some things you could try to avoid forcing polling.
 
 * [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.
+* Increase latency.
 
 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](https://github.com/guard/listen/blob/master/CONTRIBUTING.md)).
 
@@ -321,19 +188,18 @@ For questions please join us in our [Google group](http://groups.google.com/grou
 * [Travis Tilley (ttilley)][] for this awesome work on [fssm][] & [rb-fsevent][].
 * [Nathan Weizenbaum (nex3)][] for [rb-inotify][], a thorough inotify wrapper.
 * [Mathieu Arnold (mat813)][] for [rb-kqueue][], a simple kqueue wrapper.
-* [stereobooster][] for [rb-fchange][], windows support wouldn't exist without him.
+* [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 (thibaudgg)][] ([@thibaudgg](http://twitter.com/thibaudgg))
 
 ## Contributors
 
 [https://github.com/guard/listen/contributors](https://github.com/guard/listen/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
@@ -347,3 +213,4 @@ For questions please join us in our [Google group](http://groups.google.com/grou
 [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