listen 3.3.1 → 3.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e11b5e927f693205d422a0ea65147a53f65b08acde3a5dec7b370ac3f66b9707
-  data.tar.gz: 29bf36d64485cbbdc806451381d402067796430d8a5cd6ca1903a394d73d2c84
+  metadata.gz: 177b9383bf2b074aa676e65740451122818a165210268172b091a5528054dcde
+  data.tar.gz: cf3e77517acd2ce09a140c34a7349eedad081d4b4bc8e0f4e80cefd35ce9363f
 SHA512:
-  metadata.gz: 18fa31e48db9c6b9f99108e2dabed785ba15409d0d79b3b2bbcc47be0ea6c55b82418e44ce48639b32fe137fa0871623b8e593c1ffbaeee18fa4847c484cd3d9
-  data.tar.gz: a2cec7e23abba56a0b47e2f736d8fe37cb01a574da6a54049156eace74af67cf3783f2cbded1f7a2778ae1e26bbc75342144f2c16b05a30ced06ad7f91fa4e9e
+  metadata.gz: c2d73e033027eb1f2fa455a180e7abbf344bb2889ad9af7b1d79a111d55c00b4f8481c080c94ca06d8383da6ef45481e47434a25b03aba75c74839b37bf4e8b4
+  data.tar.gz: 30c3da7656d66f93ac25fc4202ef15bb813fdb6c4a7c90221ecdd49f32b267826082c4af20275454f0ada71e790ef5ac5ea20275302c66de5dedc36dc3bcb05d

data/CONTRIBUTING.md

@@ -4,7 +4,7 @@ Contribute to Listen
 File an issue
 -------------
 
-If you haven't already, first see [TROUBLESHOOTING](https://github.com/guard/listen/wiki/Troubleshooting) for known issues, solutions and workarounds.
+If you haven't already, first see [TROUBLESHOOTING](https://github.com/guard/listen/blob/master/README.md#Issues-and-Troubleshooting) for known issues, solutions and workarounds.
 
 You can report bugs and feature requests to [GitHub Issues](https://github.com/guard/listen/issues).
 
@@ -16,7 +16,7 @@ Try to figure out where the issue belongs to: Is it an issue with Listen itself
 
 **It's most likely that your bug gets resolved faster if you provide as much information as possible!**
 
-The MOST useful information is debugging output from Listen (`LISTEN_GEM_DEBUGGING=1`) - see [TROUBLESHOOTING](https://github.com/guard/listen/wiki/Troubleshooting) for details.
+The MOST useful information is debugging output from Listen (`LISTEN_GEM_DEBUGGING=1`) - see [TROUBLESHOOTING](https://github.com/guard/listen/blob/master/README.md#Issues-and-Troubleshooting) for details.
 
 
 Development

data/README.md

@@ -2,8 +2,6 @@
 
 The `listen` gem listens to file modifications and notifies you about the changes.
 
-:exclamation: `Listen` is currently accepting more maintainers. Please [read this](https://github.com/guard/guard/wiki/Maintainers) if you're interested in joining the team.
-
 [![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)
@@ -22,7 +20,7 @@ The `listen` gem listens to file modifications and notifies you about the change
 
 * 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)- see [Duplicate directory errors](https://github.com/guard/listen/wiki/Duplicate-directory-errors)).
+  * 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'`.
@@ -40,7 +38,7 @@ Pull requests or help is very welcome for these.
 The simplest way to install `listen` is to use [Bundler](http://bundler.io).
 
 ```ruby
-gem 'listen', '~> 3.3' # NOTE: for TCP functionality, use '~> 2.10' for now
+gem 'listen'
 ```
 
 ## Complete Example
@@ -240,7 +238,7 @@ If you are on Windows, it's recommended to use the [`wdm`](https://github.com/Ma
 Please add the following to your Gemfile:
 
 ```ruby
-gem 'wdm', '>= 0.1.0' if Gem.win_platform?
+gem 'wdm', '>= 0.1.0', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
 ```
 
 ### On \*BSD
@@ -259,7 +257,82 @@ end
 
 ### Getting the [polling fallback message](#options)?
 
-Please visit the [installation section of the Listen WIKI](https://github.com/guard/listen/wiki#installation) for more information and options for potential fixes.
+If you see:
+```
+Listen will be polling for changes.
+```
+
+This means the Listen gem can’t find an optimized adapter. Typically this is caused by:
+
+- 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.
+
+Possible solutions:
+
+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.
+
+#### 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.
+```
+
+### Increasing the amount of inotify watchers
+
+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 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.
+
+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.
+
+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.
+
+#### 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).
 
 ### Issues and Troubleshooting
 
@@ -267,7 +340,35 @@ If the gem doesn't work as expected, start by setting `LISTEN_GEM_DEBUGGING=debu
 
 *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.*
 
-See [TROUBLESHOOTING](https://github.com/guard/listen/wiki/Troubleshooting)
+#### 3 steps before you start diagnosing problems
+These 3 steps will:
+
+- 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)
+
+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).
+
+(see force_polling option).
+
+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).
+
+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).
 
 ## Performance
 
@@ -289,7 +390,11 @@ Also, if the directories you're watching contain many files, make sure you're:
 
 When in doubt, `LISTEN_GEM_DEBUGGING=debug` can help discover the actual events and time they happened.
 
-See also [Tips and Techniques](https://github.com/guard/listen/wiki/Tips-and-Techniques).
+## 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
 

data/bin/listen

@@ -1,12 +1,11 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'listen'
 require 'listen/cli'
 
-unless defined?(JRUBY_VERSION)
-  if Signal.list.keys.include?('INT')
-    Signal.trap('INT') { Thread.new { Listen.stop } }
-  end
+if !defined?(JRUBY_VERSION) && Signal.list.keys.include?('INT')
+  Signal.trap('INT') { Thread.new { Listen.stop } }
 end
 
 Listen::CLI.start

data/lib/listen/adapter.rb

@@ -11,7 +11,7 @@ module Listen
   module Adapter
     OPTIMIZED_ADAPTERS = [Darwin, Linux, BSD, Windows].freeze
     POLLING_FALLBACK_MESSAGE = 'Listen will be polling for changes.'\
-      'Learn more at https://github.com/guard/listen#listen-adapters.'.freeze
+      'Learn more at https://github.com/guard/listen#listen-adapters.'
 
     class << self
       def select(options = {})
@@ -24,14 +24,14 @@ module Listen
         Polling
       rescue
         Listen.logger.warn format('Adapter: failed: %s:%s', $ERROR_POSITION.inspect,
-                           $ERROR_POSITION * "\n")
+                                  $ERROR_POSITION * "\n")
         raise
       end
 
       private
 
       def _usable_adapter_class
-        OPTIMIZED_ADAPTERS.detect(&:usable?)
+        OPTIMIZED_ADAPTERS.find(&:usable?)
       end
 
       def _warn_polling_fallback(options)

data/lib/listen/adapter/base.rb

@@ -8,13 +8,11 @@ require 'listen/thread'
 module Listen
   module Adapter
     class Base
-      attr_reader :options
+      attr_reader :options, :config
 
       # TODO: only used by tests
       DEFAULTS = {}.freeze
 
-      attr_reader :config
-
       def initialize(config)
         @started = false
         @config = config
@@ -31,6 +29,7 @@ module Listen
       end
 
       # TODO: it's a separate method as a temporary workaround for tests
+      # rubocop:disable Metrics/MethodLength
       def configure
         if @configured
           Listen.logger.warn('Adapter already configured!')
@@ -57,6 +56,7 @@ module Listen
           @snapshots[dir] = snapshot
         end
       end
+      # rubocop:enable Metrics/MethodLength
 
       def started?
         @started
@@ -73,7 +73,7 @@ module Listen
         @started = true
 
         @run_thread = Listen::Thread.new("run_thread") do
-          @snapshots.values.each do |snapshot|
+          @snapshots.each_value do |snapshot|
             _timed('Record.build()') { snapshot.record.build }
           end
           _run
@@ -93,9 +93,9 @@ module Listen
       end
 
       def _timed(title)
-        start = Time.now.to_f
+        start = MonotonicTime.now
         yield
-        diff = Time.now.to_f - start
+        diff = MonotonicTime.now - start
         Listen.logger.info format('%s: %.05f seconds', title, diff)
       rescue
         Listen.logger.warn "#{title} crashed: #{$ERROR_INFO.inspect}"

data/lib/listen/adapter/bsd.rb

@@ -7,7 +7,7 @@
 module Listen
   module Adapter
     class BSD < Base
-      OS_REGEXP = /bsd|dragonfly/i
+      OS_REGEXP = /bsd|dragonfly/i.freeze
 
       DEFAULTS = {
         events: [
@@ -73,8 +73,7 @@ module Listen
       def _change(event_flags)
         { modified: [:attrib, :extend],
           added:    [:write],
-          removed:  [:rename, :delete]
-        }.each do |change, flags|
+          removed:  [:rename, :delete] }.each do |change, flags|
           return change unless (flags & event_flags).empty?
         end
         nil
@@ -87,7 +86,7 @@ module Listen
       def _watch_for_new_file(event)
         queue = event.watcher.queue
         _find(_event_path(event).to_s) do |file_path|
-          unless queue.watchers.detect { |_, v| v.path == file_path.to_s }
+          unless queue.watchers.find { |_, v| v.path == file_path.to_s }
             _watch_file(file_path, queue)
           end
         end

data/lib/listen/adapter/config.rb

@@ -5,10 +5,7 @@ require 'pathname'
 module Listen
   module Adapter
     class Config
-      attr_reader :directories
-      attr_reader :silencer
-      attr_reader :queue
-      attr_reader :adapter_options
+      attr_reader :directories, :silencer, :queue, :adapter_options
 
       def initialize(directories, queue, silencer, adapter_options)
         # Default to current directory if no directories are supplied

data/lib/listen/adapter/darwin.rb

@@ -7,7 +7,7 @@ module Listen
     # Adapter implementation for Mac OS X `FSEvents`.
     #
     class Darwin < Base
-      OS_REGEXP = /darwin(?<major_version>(1|2)\d+)/i
+      OS_REGEXP = /darwin(?<major_version>(1|2)\d+)/i.freeze
 
       # The default delay between checking for changes.
       DEFAULTS = { latency: 0.1 }.freeze
@@ -51,7 +51,7 @@ module Listen
 
       def _process_changes(dirs)
         dirs.each do |dir|
-          dir = Pathname.new(dir.sub(%r{\/$}, ''))
+          dir = Pathname.new(dir.sub(%r{/$}, ''))
 
           @callbacks.each do |watched_dir, callback|
             if watched_dir.eql?(dir) || Listen::Directory.ascendant_of?(watched_dir, dir)

data/lib/listen/adapter/linux.rb

@@ -4,7 +4,7 @@ module Listen
   module Adapter
     # @see https://github.com/nex3/rb-inotify
     class Linux < Base
-      OS_REGEXP = /linux/i
+      OS_REGEXP = /linux/i.freeze
 
       DEFAULTS = {
         events: [
@@ -21,12 +21,12 @@ module Listen
 
       private
 
-      WIKI_URL = 'https://github.com/guard/listen'\
-        '/wiki/Increasing-the-amount-of-inotify-watchers'.freeze
+      README_URL = 'https://github.com/guard/listen'\
+        '/blob/master/README.md#increasing-the-amount-of-inotify-watchers'
 
-      INOTIFY_LIMIT_MESSAGE = <<-EOS.gsub(/^\s*/, '')
+      INOTIFY_LIMIT_MESSAGE = <<-EOS
         FATAL: Listen error: unable to monitor directories for changes.
-        Visit #{WIKI_URL} for info on how to fix this.
+        Visit #{README_URL} for info on how to fix this.
       EOS
 
       def _configure(directory, &callback)
@@ -41,6 +41,7 @@ module Listen
         @worker.run
       end
 
+      # rubocop:disable Metrics/MethodLength
       def _process_event(dir, event)
         # NOTE: avoid using event.absolute_name since new API
         # will need to have a custom recursion implemented
@@ -73,6 +74,7 @@ module Listen
 
         _queue_change(:file, dir, rel_path, params)
       end
+      # rubocop:enable Metrics/MethodLength
 
       def _skip_event?(event)
         # Event on root directory

data/lib/listen/adapter/polling.rb

@@ -8,7 +8,7 @@ module Listen
     # file IO than the other implementations.
     #
     class Polling < Base
-      OS_REGEXP = // # match every OS
+      OS_REGEXP = //.freeze # match every OS
 
       DEFAULTS = { latency: 1.0, wait_for_delay: 0.05 }.freeze
 
@@ -21,12 +21,13 @@ module Listen
 
       def _run
         loop do
-          start = Time.now.to_f
+          start = MonotonicTime.now
           @polling_callbacks.each do |callback|
             callback.call(nil)
-            nap_time = options.latency - (Time.now.to_f - start)
-            # TODO: warn if nap_time is negative (polling too slow)
-            sleep(nap_time) if nap_time > 0
+            if (nap_time = options.latency - (MonotonicTime.now - start)) > 0
+              # TODO: warn if nap_time is negative (polling too slow)
+              sleep(nap_time)
+            end
           end
         end
       end

data/lib/listen/adapter/windows.rb

@@ -5,7 +5,7 @@ module Listen
     # Adapter implementation for Windows `wdm`.
     #
     class Windows < Base
-      OS_REGEXP = /mswin|mingw|cygwin/i
+      OS_REGEXP = /mswin|mingw|cygwin/i.freeze
 
       BUNDLER_DECLARE_GEM = <<-EOS.gsub(/^ {6}/, '')
         Please add the following to your Gemfile to avoid polling for changes:
@@ -18,7 +18,7 @@ module Listen
         true
       rescue LoadError
         Listen.logger.debug format('wdm - load failed: %s:%s', $ERROR_INFO,
-                            $ERROR_POSITION * "\n")
+                                   $ERROR_POSITION * "\n")
 
         Kernel.warn BUNDLER_DECLARE_GEM
         false
@@ -38,8 +38,7 @@ module Listen
           yield([:dir, change])
         end
 
-        events = [:attributes, :last_write]
-        @worker.watch_recursively(dir.to_s, *events) do |change|
+        @worker.watch_recursively(dir.to_s, :attributes, :last_write) do |change|
           yield([:attr, change])
         end
       end
@@ -48,6 +47,7 @@ module Listen
         @worker.run!
       end
 
+      # rubocop:disable Metrics/MethodLength
       def _process_event(dir, event)
         Listen.logger.debug "wdm - callback: #{event.inspect}"
 
@@ -67,10 +67,11 @@ module Listen
             _queue_change(:file, dir, rel_path, options)
           end
         when :dir
-          if change.type == :removed
+          case change.type
+          when :removed
             # TODO: check if watched dir?
             _queue_change(:dir, dir, Pathname(rel_path).dirname.to_s, {})
-          elsif change.type == :added
+          when :added
             _queue_change(:dir, dir, rel_path, {})
             # do nothing - changed directory means either:
             #   - removed subdirs (handled above)
@@ -80,20 +81,15 @@ module Listen
             # so what's left?
           end
         end
-      rescue
-        details = event.inspect
-        Listen.logger.error format('wdm - callback (%s): %s:%s', details, $ERROR_INFO,
-                            $ERROR_POSITION * "\n")
-        raise
       end
+      # rubocop:enable Metrics/MethodLength
 
       def _change(type)
         { modified: [:modified, :attrib], # TODO: is attrib really passed?
           added:    [:added, :renamed_new_file],
-          removed:  [:removed, :renamed_old_file] }.each do |change, types|
-          return change if types.include?(type)
+          removed:  [:removed, :renamed_old_file] }.find do |change, types|
+          types.include?(type) and break change
         end
-        nil
       end
     end
   end