listen 3.3.3 → 3.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e8a5f611b09b7689da35117369be07e2cb74ed77575dc7d894c12629767ad82
-  data.tar.gz: c7995d9785eb3202fa13528489a0c48e54c70fc201c750cb885777d36151b316
+  metadata.gz: 3502b7f13a7eb3801aa2ccfb12825f13ce550b6339316389a17ed6319c3c450d
+  data.tar.gz: 433b372d311ea535f67999d23ef947dd3e4358849a60467dcf41582387d04b0f
 SHA512:
-  metadata.gz: fb0d331747afe760ab96a3eecf20d041e1e9fec0a2c49b678289fe56250c2a357a4826c9d4c9da38c9db7f819e7d61f6b9f5245c23a34c4eb9f77868abde2ec0
-  data.tar.gz: 3c7d8b1f91224ea4a10b4f039e334fbb85c0eae14996bf2df9c32a9487325f94a5e1d1ce87abefa23dce2f50b0bac2069950d05ec1f561552fb9c8493c31fd83
+  metadata.gz: 9a522a4498c0369db11679d60a7702e348f41442c33aa25e292807b91aa42fd7a672ed2ce77f1993c30da16b1dcae2733ecf2ddd70bbbd9a1bd89c8192483199
+  data.tar.gz: e8f695e75d67aa62ad4f3bd5e7d237717b7f58f1e6d444099697c901b21d49ed144250eca0ef3987dd33c625de4e181b86e57f35fdc839ccdb0b6a3b3578bf75

data/README.md

@@ -22,7 +22,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 +40,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 +240,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 +259,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 +342,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 +392,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/lib/listen/adapter/linux.rb

@@ -22,7 +22,7 @@ module Listen
       private
 
       WIKI_URL = 'https://github.com/guard/listen'\
-        '/wiki/Increasing-the-amount-of-inotify-watchers'
+        '/blob/master/README.md#increasing-the-amount-of-inotify-watchers'
 
       INOTIFY_LIMIT_MESSAGE = <<-EOS.gsub(/^\s*/, '')
         FATAL: Listen error: unable to monitor directories for changes.

data/lib/listen/record.rb

@@ -45,10 +45,11 @@ module Listen
     end
 
     def dir_entries(rel_path)
-      subtree = if [nil, '', '.'].include? rel_path.to_s
+      subtree = if ['', '.'].include? rel_path.to_s
         @tree
       else
-        _sub_tree(rel_path)
+        @tree[rel_path.to_s] ||= _auto_hash
+        @tree[rel_path.to_s]
       end
 
       subtree.transform_values do |values|
@@ -57,19 +58,6 @@ module Listen
       end
     end
 
-    def _sub_tree(rel_path)
-      @tree.each_with_object({}) do |(path, meta), result|
-        next unless path.start_with?(rel_path)
-
-        if path == rel_path
-          result.merge!(meta)
-        else
-          sub_path         = path.sub(%r{\A#{rel_path}/?}, '')
-          result[sub_path] = meta
-        end
-      end
-    end
-
     def build
       @tree = _auto_hash
       # TODO: test with a file name given

data/lib/listen/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Listen
-  VERSION = '3.3.3'
+  VERSION = '3.3.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: listen
 version: !ruby/object:Gem::Version
-  version: 3.3.3
+  version: 3.3.4
 platform: ruby
 authors:
 - Thibaud Guillaume-Gentil
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-11-30 00:00:00.000000000 Z
+date: 2020-12-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb-fsevent
@@ -101,9 +101,9 @@ metadata:
   allowed_push_host: https://rubygems.org
   bug_tracker_uri: https://github.com/guard/listen/issues
   changelog_uri: https://github.com/guard/listen/releases
-  documentation_uri: https://www.rubydoc.info/gems/listen/3.3.3
+  documentation_uri: https://www.rubydoc.info/gems/listen/3.3.4
   homepage_uri: https://github.com/guard/listen
-  source_code_uri: https://github.com/guard/listen/tree/v3.3.3
+  source_code_uri: https://github.com/guard/listen/tree/v3.3.4
   wiki_uri: https://github.com/guard/listen/wiki
 post_install_message: 
 rdoc_options: []