listen 2.8.2 → 2.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 82833c1dcd0ed421fcb93115f1c764492148b1f4
-  data.tar.gz: 407619ca1bdba240ae918e4e3e73e237f129f132
+  metadata.gz: c41f2fe5cb60a1128a34a6df435da8325c245a31
+  data.tar.gz: ae4b18a4f893dcb9f2dea2065e75fd7d0af88335
 SHA512:
-  metadata.gz: 03f0ba222830c725718adf106e479a559b183d663009c7482c35bf252c9c41799d3d824692ac30716ddf62ada053610400391b67c3d8caa82eb9a715ad3d16d7
-  data.tar.gz: eaa55b1eaae113d97e621f6de5fb657186f584f0d1c6cd1051c17368702867e6b816047d9868114863118addbc73f413f7850b040d49c2631eb0699ae6b84763
+  metadata.gz: f3e6697f836c76a4dd24cf9440d8426563da850c58d7c1a698197d674879df4f7370a42b96c456842f942a321ea06fc201ac9d1d5d4511568bf06e8eb1d26463
+  data.tar.gz: 6659d1b8a8bc42c43e79993551bd3cd16ce89916292fe2400260d94c0e3bf1c60a31bbbd1397e1b09ef4841053abb342210337b9f56832e614ea5bd411d2b29c

data/README.md

@@ -6,29 +6,22 @@
 
 The Listen gem listens to file modifications and notifies you about the changes.
 
-## IMPORTANT NOTE
+## Known issues / Quickfixes / Workarounds
 
-Got an issue with Listen and you're "in a hurry"? First, try Polling mode as a workaround (described below).
+Just head over here: https://github.com/guard/listen/wiki/Quickfixes,-known-issues-and-workarounds
 
-Otherwise ...
-
-Output from using `LISTEN_GEM_DEBUGGING` (debug mode) is often *crucial* to quickly diagnosing and fixing issues.
-
-There are TOO MANY possible and surprising reasons why Listen "doesn't work as expected" (e.g. Dropbox folders, editor settings, system limits) - and the best way to find out is by going through these 3 steps first:
-
-See [TROUBLESHOOTING](https://github.com/guard/listen/blob/master/TROUBLESHOOTING.md)
-
-Once you've reproduced the problem in debug mode (`LISTEN_GEM_DEBUGGING`), paste the output it into a Gist and link it to your issue.
+## Tips and Techniques
 
+Make sure you know these few basic tricks: https://github.com/guard/listen/wiki/Tips-and-Techniques
 
 ## Features
 
-* Supports watching multiple directories from a single listener.
-* OS-specific adapters on MRI for Mac OS X 10.6+, Linux, ~~\*BSD~~ and Windows, [more info](#listen-adapters) below.
+* 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.
-* Allows supplying regexp-patterns to ignore paths for better results.
-* File content checksum comparison for modifications made under the same second (OS X HFS volumes, VFAT volumes).
+* You can watch multiple directories.
+* Regexp-patterns for ignoring paths for more accuracy and speed
 * Forwarding file events over TCP, [more info](#forwarding-file-events-over-tcp) below.
+* Increased change detection accuracy on OS X HFS and VFAT volumes.
 * Tested on MRI Ruby environments (1.9+ only) via [Travis CI](https://travis-ci.org/guard/listen),
 
 Please note that:
@@ -37,10 +30,9 @@ Please note that:
 - Windows and \*BSD adapter aren't continuously and automaticaly tested.
 - \*BSD is broken and not supported any more, see: [#220](https://github.com/guard/listen/issues/220)
 
-
 ## Pending features / issues
 
-* Ignored directories are actually still scanned [#274](https://github.com/guard/listen/issues/274) (Except when polling)
+* symlinked directories aren't fully transparent yet: https://github.com/guard/listen/issues/279
 * Directory/adapter specific configuration options
 * Support for plugins
 
@@ -51,7 +43,7 @@ Pull request or help is very welcome for these.
 The simplest way to install Listen is to use [Bundler](http://bundler.io).
 
 ```ruby
-gem 'listen', '~> 2.0'
+gem 'listen', '~> 2.7' # this prevents upgrading to 3.x
 ```
 
 ## Usage
@@ -105,6 +97,8 @@ sleep
 
 Note: Ignoring regexp patterns are evaluated against relative paths.
 
+Note: ignoring paths does not improve performance - except when Polling
+
 ### Only
 
 Listen catches all files (less the ignored once) by default, if you want to only listen to a specific type of file (ie: just rb extension) you should use the `only` option/method.
@@ -170,11 +164,11 @@ wait_for_delay: 4                               # Set the delay (**in seconds**)
 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."
-
 debug: true                                     # Enable Celluloid logger
                                                 # 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#polling-fallback."
 ```
 
 Also, setting the environment variable `LISTEN_GEM_DEBUGGING=1` does the same as `debug: true` above.
@@ -242,13 +236,14 @@ If Listen seems slow or unresponsive, make sure you're not using the Polling ada
 Also, if the directories you're watching contain many files, make sure you're:
 
 * not using Polling (ideally)
-* using `:ignore` and `:only` options to avoid tracking directories you don't care about
+* 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=2)
 * 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
-* running Listen with the `:latency` and `:wait_for_delay` options not too small or too big (depends on needs)
 * 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
 

data/lib/listen/record.rb

@@ -115,8 +115,9 @@ module Listen
 
     def _fast_build_dir(remaining, symlink_detector)
       entry = remaining.pop
+      children = entry.children # NOTE: children() implicitly tests if dir
       symlink_detector.verify_unwatched!(entry)
-      entry.children.each { |child| remaining << child }
+      children.each { |child| remaining << child }
       add_dir(entry.root, entry.record_dir_key)
     rescue Errno::ENOTDIR
       _fast_try_file(entry)

data/lib/listen/version.rb

@@ -1,3 +1,3 @@
 module Listen
-  VERSION = '2.8.2'
+  VERSION = '2.8.3'
 end

data/spec/lib/listen/record_spec.rb

@@ -7,6 +7,46 @@ describe Listen::Record do
     instance_double(Listen::Listener, registry: registry, options: {})
   end
 
+  def dir_entries_for(hash)
+    hash.each do |dir, entries|
+      allow(::Dir).to receive(:entries).with(dir) { entries }
+    end
+  end
+
+  def real_directory(hash)
+    dir_entries_for(hash)
+    hash.each do |dir, _|
+      realpath(dir)
+    end
+  end
+
+  def file(path)
+    allow(::Dir).to receive(:entries).with(path).and_raise(Errno::ENOTDIR)
+    path
+  end
+
+  def lstat(path, stat = nil)
+    stat ||= instance_double(::File::Stat, mtime: 2.3, mode: 0755)
+    allow(::File).to receive(:lstat).with(path).and_return(stat)
+    stat
+  end
+
+  def realpath(path)
+    allow(::File).to receive(:realpath).with(path).and_return(path)
+    path
+  end
+
+  def symlink(hash_or_dir)
+    if String === hash_or_dir
+      allow(::File).to receive(:realpath).with(hash_or_dir).
+        and_return(hash_or_dir)
+    else
+      hash_or_dir.each do |dir, real_path|
+        allow(::File).to receive(:realpath).with(dir).and_return(real_path)
+      end
+    end
+  end
+
   let(:record) { Listen::Record.new(listener) }
   let(:dir) { instance_double(Pathname, to_s: '/dir') }
 
@@ -208,9 +248,8 @@ describe Listen::Record do
     end
 
     it 're-inits paths' do
-      allow(::Dir).to receive(:entries).and_return([])
-      allow(::File).to receive(:realpath).with('/dir1').and_return('/dir1')
-      allow(::File).to receive(:realpath).with('/dir2').and_return('/dir2')
+      real_directory('/dir1' => [])
+      real_directory('/dir2' => [])
 
       record.update_file(dir, 'path/file.rb', mtime: 1.1)
       record.build
@@ -223,19 +262,10 @@ describe Listen::Record do
 
     context 'with no subdirs' do
       before do
-        allow(::Dir).to receive(:entries).with('/dir1') { %w(foo bar) }
-        allow(::Dir).to receive(:entries).with('/dir1/foo').and_raise(Errno::ENOTDIR)
-        allow(::Dir).to receive(:entries).with('/dir1/bar').and_raise(Errno::ENOTDIR)
-        allow(::File).to receive(:lstat).with('/dir1/foo') { foo_stat }
-        allow(::File).to receive(:lstat).with('/dir1/bar') { bar_stat }
-        allow(::Dir).to receive(:entries).with('/dir2') { [] }
-
-        allow(::File).to receive(:realpath).with('/dir1').and_return('/dir1')
-        allow(::File).to receive(:realpath).with('/dir2').and_return('/dir2')
-        allow(::File).to receive(:realpath).with('/dir1/foo').
-          and_return('/dir1/foo')
-        allow(::File).to receive(:realpath).with('/dir1/bar').
-          and_return('/dir1/bar')
+        real_directory('/dir1' => %w(foo bar))
+        lstat(file('/dir1/foo'), foo_stat)
+        lstat(file('/dir1/bar'), bar_stat)
+        real_directory('/dir2' => [])
       end
 
       it 'builds record' do
@@ -250,18 +280,10 @@ describe Listen::Record do
 
     context 'with subdir containing files' do
       before do
-        allow(::Dir).to receive(:entries).with('/dir1') { %w(foo) }
-        allow(::Dir).to receive(:entries).with('/dir1/foo') { %w(bar) }
-        allow(::Dir).to receive(:entries).with('/dir1/foo/bar').and_raise(Errno::ENOTDIR)
-        allow(::File).to receive(:lstat).with('/dir1/foo/bar') { bar_stat }
-        allow(::Dir).to receive(:entries).with('/dir2') { [] }
-
-        allow(::File).to receive(:realpath).with('/dir1').and_return('/dir1')
-        allow(::File).to receive(:realpath).with('/dir2').and_return('/dir2')
-        allow(::File).to receive(:realpath).with('/dir1/foo').
-          and_return('/dir1/foo')
-        allow(::File).to receive(:realpath).with('/dir1/foo/bar').
-          and_return('/dir1/foo/bar')
+        real_directory('/dir1' => %w(foo))
+        real_directory('/dir1/foo' => %w(bar))
+        lstat(file('/dir1/foo/bar'))
+        real_directory('/dir2' => [])
       end
 
       it 'builds record'  do
@@ -275,12 +297,13 @@ describe Listen::Record do
 
     context 'with subdir containing dirs' do
       before do
+        real_directory('/dir1' => %w(foo))
+        real_directory('/dir1/foo' => %w(bar baz))
+        real_directory('/dir1/foo/bar' => [])
+        real_directory('/dir1/foo/baz' => [])
+        real_directory('/dir2' => [])
+
         allow(::File).to receive(:realpath) { |path| path }
-        allow(::Dir).to receive(:entries).with('/dir1') { %w(foo) }
-        allow(::Dir).to receive(:entries).with('/dir1/foo') { %w(bar baz) }
-        allow(::Dir).to receive(:entries).with('/dir1/foo/bar') { [] }
-        allow(::Dir).to receive(:entries).with('/dir1/foo/baz') { [] }
-        allow(::Dir).to receive(:entries).with('/dir2') { [] }
       end
 
       it 'builds record'  do
@@ -299,15 +322,14 @@ describe Listen::Record do
     context 'with subdir containing symlink to parent' do
       subject { record.paths }
       before do
-        allow(::Dir).to receive(:entries).with('/dir1') { %w(foo) }
-        allow(::Dir).to receive(:entries).with('/dir1/foo') { %w(foo) }
-        allow(::Dir).to receive(:entries).with('/dir2') { [] }
-        allow(::File).to receive(:realpath).with('/dir1').and_return('/bar')
-        allow(::File).to receive(:realpath).with('/dir1/foo').and_return('/bar')
-        allow(::File).to receive(:realpath).with('/dir2').and_return('/dir2')
+        real_directory('/dir1' => %w(foo))
+        dir_entries_for('/dir1/foo' => %w(dir1))
+        symlink('/dir1/foo' => '/dir1')
+
+        real_directory('/dir2' => [])
       end
 
-      it 'shows message and aborts with error' do
+      it 'shows a warning' do
         expect(STDERR).to receive(:puts).
           with(/directory is already being watched/)
 
@@ -316,5 +338,40 @@ describe Listen::Record do
         # to raise_error(RuntimeError, /Failed due to looped symlinks/)
       end
     end
+
+    context 'with a normal symlinked directory to another' do
+      subject { record.paths }
+
+      before do
+        real_directory('/dir1' => %w(foo))
+
+        symlink('/dir1/foo' => '/dir2')
+        dir_entries_for('/dir1/foo' => %w(bar))
+        lstat(realpath(file('/dir1/foo/bar')))
+
+        real_directory('/dir2' => %w(bar))
+        lstat(file('/dir2/bar'))
+      end
+
+      it 'shows message' do
+        expect(STDERR).to_not receive(:puts)
+        record.build
+      end
+    end
+
+    context 'with subdir containing symlinked file' do
+      subject { record.paths }
+      before do
+        real_directory('/dir1' => %w(foo))
+        lstat(file('/dir1/foo'))
+        real_directory('/dir2' => [])
+      end
+
+      it 'shows a warning' do
+        expect(STDERR).to_not receive(:puts)
+
+        record.build
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: listen
 version: !ruby/object:Gem::Version
-  version: 2.8.2
+  version: 2.8.3
 platform: ruby
 authors:
 - Thibaud Guillaume-Gentil
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-25 00:00:00.000000000 Z
+date: 2014-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: celluloid