listen 3.2.1 → 3.4.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CONTRIBUTING.md +2 -2
- data/README.md +220 -70
- data/bin/listen +3 -4
- data/lib/listen.rb +15 -20
- data/lib/listen/adapter.rb +9 -11
- data/lib/listen/adapter/base.rb +22 -34
- data/lib/listen/adapter/bsd.rb +6 -5
- data/lib/listen/adapter/config.rb +3 -4
- data/lib/listen/adapter/darwin.rb +11 -13
- data/lib/listen/adapter/linux.rb +14 -9
- data/lib/listen/adapter/polling.rb +8 -5
- data/lib/listen/adapter/windows.rb +15 -17
- data/lib/listen/backend.rb +2 -0
- data/lib/listen/change.rb +14 -21
- data/lib/listen/cli.rb +6 -6
- data/lib/listen/directory.rb +8 -8
- data/lib/listen/error.rb +10 -0
- data/lib/listen/event/config.rb +9 -24
- data/lib/listen/event/loop.rb +44 -67
- data/lib/listen/event/processor.rb +41 -37
- data/lib/listen/event/queue.rb +12 -13
- data/lib/listen/file.rb +15 -2
- data/lib/listen/fsm.rb +72 -71
- data/lib/listen/listener.rb +26 -23
- data/lib/listen/listener/config.rb +4 -4
- data/lib/listen/logger.rb +24 -20
- data/lib/listen/monotonic_time.rb +27 -0
- data/lib/listen/options.rb +11 -8
- data/lib/listen/queue_optimizer.rb +9 -12
- data/lib/listen/record.rb +30 -31
- data/lib/listen/record/entry.rb +4 -2
- data/lib/listen/record/symlink_detector.rb +10 -8
- data/lib/listen/silencer.rb +12 -8
- data/lib/listen/silencer/controller.rb +2 -0
- data/lib/listen/thread.rb +54 -0
- data/lib/listen/version.rb +3 -1
- metadata +13 -22
- data/lib/listen/internals/thread_pool.rb +0 -29
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 177b9383bf2b074aa676e65740451122818a165210268172b091a5528054dcde
|
4
|
+
data.tar.gz: cf3e77517acd2ce09a140c34a7349eedad081d4b4bc8e0f4e80cefd35ce9363f
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: c2d73e033027eb1f2fa455a180e7abbf344bb2889ad9af7b1d79a111d55c00b4f8481c080c94ca06d8383da6ef45481e47434a25b03aba75c74839b37bf4e8b4
|
7
|
+
data.tar.gz: 30c3da7656d66f93ac25fc4202ef15bb813fdb6c4a7c90221ecdd49f32b267826082c4af20275454f0ada71e790ef5ac5ea20275302c66de5dedc36dc3bcb05d
|
data/CONTRIBUTING.md
CHANGED
@@ -4,7 +4,7 @@ Contribute to Listen
|
|
4
4
|
File an issue
|
5
5
|
-------------
|
6
6
|
|
7
|
-
If you haven't already, first see [TROUBLESHOOTING](https://github.com/guard/listen/
|
7
|
+
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.
|
8
8
|
|
9
9
|
You can report bugs and feature requests to [GitHub Issues](https://github.com/guard/listen/issues).
|
10
10
|
|
@@ -16,7 +16,7 @@ Try to figure out where the issue belongs to: Is it an issue with Listen itself
|
|
16
16
|
|
17
17
|
**It's most likely that your bug gets resolved faster if you provide as much information as possible!**
|
18
18
|
|
19
|
-
The MOST useful information is debugging output from Listen (`LISTEN_GEM_DEBUGGING=1`) - see [TROUBLESHOOTING](https://github.com/guard/listen/
|
19
|
+
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.
|
20
20
|
|
21
21
|
|
22
22
|
Development
|
data/README.md
CHANGED
@@ -1,12 +1,11 @@
|
|
1
|
-
## IMPORTANT: If you cannot install Listen (e.g. on Travis/CI builds), [a workaround is here](https://github.com/guard/listen/wiki/Ruby-version-requirements)
|
2
|
-
|
3
|
-
: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.
|
4
|
-
|
5
1
|
# Listen
|
6
2
|
|
7
|
-
|
3
|
+
The `listen` gem listens to file modifications and notifies you about the changes.
|
8
4
|
|
9
|
-
|
5
|
+
[![Development Status](https://github.com/guard/listen/workflows/Development/badge.svg)](https://github.com/guard/listen/actions?workflow=Development)
|
6
|
+
[![Gem Version](https://badge.fury.io/rb/listen.svg)](http://badge.fury.io/rb/listen)
|
7
|
+
[![Code Climate](https://codeclimate.com/github/guard/listen.svg)](https://codeclimate.com/github/guard/listen)
|
8
|
+
[![Coverage Status](https://coveralls.io/repos/guard/listen/badge.svg?branch=master)](https://coveralls.io/r/guard/listen)
|
10
9
|
|
11
10
|
## Features
|
12
11
|
|
@@ -15,46 +14,90 @@ The Listen gem listens to file modifications and notifies you about the changes.
|
|
15
14
|
* You can watch multiple directories.
|
16
15
|
* Regexp-patterns for ignoring paths for more accuracy and speed
|
17
16
|
* Increased change detection accuracy on OS X HFS and VFAT volumes.
|
18
|
-
*
|
17
|
+
* Continuous Integration: tested on selected Ruby environments via [Github Workflows](https:///github.com/guard/listen/master/.github/workflows).
|
19
18
|
|
20
19
|
## Issues / limitations
|
21
20
|
|
22
21
|
* Limited support for symlinked directories ([#279](https://github.com/guard/listen/issues/279)):
|
23
22
|
* Symlinks are always followed ([#25](https://github.com/guard/listen/issues/25)).
|
24
|
-
* Symlinked directories pointing within a watched directory are not supported ([#273](https://github.com/guard/listen/pull/273)
|
23
|
+
* Symlinked directories pointing within a watched directory are not supported ([#273](https://github.com/guard/listen/pull/273).
|
25
24
|
* No directory/adapter-specific configuration options.
|
26
25
|
* Support for plugins planned for future.
|
27
|
-
* TCP functionality was removed in
|
26
|
+
* 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'`.
|
28
27
|
* Some filesystems won't work without polling (VM/Vagrant Shared folders, NFS, Samba, sshfs, etc.).
|
29
28
|
* Specs suite on JRuby and Rubinius aren't reliable on Travis CI, but should work.
|
30
29
|
* Windows and \*BSD adapter aren't continuously and automatically tested.
|
31
30
|
* OSX adapter has some performance limitations ([#342](https://github.com/guard/listen/issues/342)).
|
32
|
-
*
|
31
|
+
* FreeBSD users need patched version of rb-kqueue (as of 2020/11). See #475 for the issue, mat813/rb-kqueue#12 for the patch, and Bug 250432 in bugzilla.
|
33
32
|
* 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).
|
34
33
|
|
35
34
|
Pull requests or help is very welcome for these.
|
36
35
|
|
37
36
|
## Install
|
38
37
|
|
39
|
-
The simplest way to install
|
38
|
+
The simplest way to install `listen` is to use [Bundler](http://bundler.io).
|
40
39
|
|
41
40
|
```ruby
|
42
|
-
gem 'listen'
|
41
|
+
gem 'listen'
|
42
|
+
```
|
43
|
+
|
44
|
+
## Complete Example
|
45
|
+
Here is a complete example of using the `listen` gem:
|
46
|
+
```ruby
|
47
|
+
require 'listen'
|
48
|
+
|
49
|
+
listener = Listen.to('/srv/app') do |modified, added, removed|
|
50
|
+
puts(modified: modified, added: added, removed: removed)
|
51
|
+
end
|
52
|
+
listener.start
|
53
|
+
sleep
|
54
|
+
```
|
55
|
+
Running the above in the background, you can see the callback block being called in response to each command:
|
56
|
+
```
|
57
|
+
$ cd /srv/app
|
58
|
+
$ touch a.txt
|
59
|
+
{:modified=>[], :added=>["/srv/app/a.txt"], :removed=>[]}
|
60
|
+
|
61
|
+
$ echo more >> a.txt
|
62
|
+
{:modified=>["/srv/app/a.txt"], :added=>[], :removed=>[]}
|
63
|
+
|
64
|
+
$ mv a.txt b.txt
|
65
|
+
{:modified=>[], :added=>["/srv/app/b.txt"], :removed=>["/srv/app/a.txt"]}
|
66
|
+
|
67
|
+
$ vi b.txt
|
68
|
+
# add a line to this new file and press ZZ to save and exit
|
69
|
+
{:modified=>["/srv/app/b.txt"], :added=>[], :removed=>[]}
|
70
|
+
|
71
|
+
$ vi c.txt
|
72
|
+
# add a line and press ZZ to save and exit
|
73
|
+
{:modified=>[], :added=>["/srv/app/c.txt"], :removed=>[]}
|
74
|
+
|
75
|
+
$ rm b.txt c.txt
|
76
|
+
{:modified=>[], :added=>[], :removed=>["/srv/app/b.txt", "/srv/app/c.txt"]}
|
43
77
|
```
|
44
78
|
|
45
79
|
## Usage
|
46
80
|
|
47
|
-
Call `Listen.to` with
|
81
|
+
Call `Listen.to` with one or more directories and the "changes" callback passed as a block.
|
48
82
|
|
49
83
|
``` ruby
|
50
84
|
listener = Listen.to('dir/to/listen', 'dir/to/listen2') do |modified, added, removed|
|
51
|
-
puts "modified absolute path: #{modified}"
|
52
|
-
puts "added absolute path: #{added}"
|
53
|
-
puts "removed absolute path: #{removed}"
|
85
|
+
puts "modified absolute path array: #{modified}"
|
86
|
+
puts "added absolute path array: #{added}"
|
87
|
+
puts "removed absolute path array: #{removed}"
|
54
88
|
end
|
55
|
-
listener.start # not
|
89
|
+
listener.start # starts a listener thread--does not block
|
90
|
+
|
91
|
+
# do whatever you want here...just don't exit the process :)
|
92
|
+
|
56
93
|
sleep
|
57
94
|
```
|
95
|
+
## Changes Callback
|
96
|
+
|
97
|
+
Changes to the listened-to directories are reported by the listener thread in a callback.
|
98
|
+
The callback receives **three** array parameters: `modified`, `added` and `removed`, in that order.
|
99
|
+
Each of these three is always an array with 0 or more entries.
|
100
|
+
Each array entry is an absolute path.
|
58
101
|
|
59
102
|
### Pause / unpause / stop
|
60
103
|
|
@@ -75,13 +118,14 @@ listener.unpause # resumes processing changes ("start" would do the same)
|
|
75
118
|
listener.stop # stop both listening to changes and processing them
|
76
119
|
```
|
77
120
|
|
78
|
-
Note: While paused,
|
121
|
+
Note: While paused, `listen` keeps on collecting changes in the background - to clear them, call `stop`.
|
79
122
|
|
80
|
-
Note: You should keep track of all started listeners and stop them properly on finish.
|
123
|
+
Note: You should keep track of all started listeners and `stop` them properly on finish.
|
81
124
|
|
82
125
|
### Ignore / ignore!
|
83
126
|
|
84
|
-
Listen ignores some directories and extensions by default (See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer)
|
127
|
+
`Listen` ignores some directories and extensions by default (See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer).
|
128
|
+
You can add ignoring patterns with the `ignore` option/method or overwrite default with `ignore!` option/method.
|
85
129
|
|
86
130
|
``` ruby
|
87
131
|
listener = Listen.to('dir/path/to/listen', ignore: /\.txt/) { |modified, added, removed| # ... }
|
@@ -93,11 +137,11 @@ sleep
|
|
93
137
|
|
94
138
|
Note: `:ignore` regexp patterns are evaluated against relative paths.
|
95
139
|
|
96
|
-
Note: Ignoring paths does not improve performance, except when Polling ([#274](https://github.com/guard/listen/issues/274))
|
140
|
+
Note: Ignoring paths does not improve performance, except when Polling ([#274](https://github.com/guard/listen/issues/274)).
|
97
141
|
|
98
142
|
### Only
|
99
143
|
|
100
|
-
Listen
|
144
|
+
`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.
|
101
145
|
|
102
146
|
``` ruby
|
103
147
|
listener = Listen.to('dir/path/to/listen', only: /\.rb$/) { |modified, added, removed| # ... }
|
@@ -109,35 +153,6 @@ sleep
|
|
109
153
|
Note: `:only` regexp patterns are evaluated only against relative **file** paths.
|
110
154
|
|
111
155
|
|
112
|
-
## Changes callback
|
113
|
-
|
114
|
-
Changes to the listened-to directories gets reported back to the user in a callback.
|
115
|
-
The registered callback gets invoked, when there are changes, with **three** parameters:
|
116
|
-
`modified`, `added` and `removed` paths, in that particular order.
|
117
|
-
Paths are always returned in their absolute form.
|
118
|
-
|
119
|
-
Example:
|
120
|
-
|
121
|
-
```ruby
|
122
|
-
listener = Listen.to('path/to/app') do |modified, added, removed|
|
123
|
-
# This block will be called when there are changes.
|
124
|
-
end
|
125
|
-
listener.start
|
126
|
-
sleep
|
127
|
-
```
|
128
|
-
|
129
|
-
or ...
|
130
|
-
|
131
|
-
```ruby
|
132
|
-
# Create a callback
|
133
|
-
callback = Proc.new do |modified, added, removed|
|
134
|
-
# This proc will be called when there are changes.
|
135
|
-
end
|
136
|
-
listener = Listen.to('dir', &callback)
|
137
|
-
listener.start
|
138
|
-
sleep
|
139
|
-
```
|
140
|
-
|
141
156
|
## Options
|
142
157
|
|
143
158
|
All the following options can be set through the `Listen.to` after the directory path(s) params.
|
@@ -167,16 +182,42 @@ polling_fallback_message: 'custom message' # Set a custom polling fallback
|
|
167
182
|
# default: "Listen will be polling for changes. Learn more at https://github.com/guard/listen#listen-adapters."
|
168
183
|
```
|
169
184
|
|
170
|
-
## Debugging
|
185
|
+
## Logging and Debugging
|
171
186
|
|
172
|
-
|
187
|
+
`Listen` logs its activity to `Listen.logger`.
|
188
|
+
This is the primary method of debugging.
|
189
|
+
|
190
|
+
### Custom Logger
|
191
|
+
You can call `Listen.logger =` to set a custom `listen` logger for the process. For example:
|
192
|
+
```
|
193
|
+
Listen.logger = Rails.logger
|
194
|
+
```
|
173
195
|
|
174
|
-
|
196
|
+
### Default Logger
|
197
|
+
If no custom logger is set, a default `listen` logger which logs to to `STDERR` will be created and assigned to `Listen.logger`.
|
175
198
|
|
199
|
+
The default logger defaults to the `error` logging level (severity).
|
200
|
+
You can override the logging level by setting the environment variable `LISTEN_GEM_DEBUGGING=<level>`.
|
201
|
+
For `<level>`, all standard `::Logger` levels are supported, with any mix of upper-/lower-case:
|
202
|
+
```
|
203
|
+
export LISTEN_GEM_DEBUGGING=debug # or 2 [deprecated]
|
204
|
+
export LISTEN_GEM_DEBUGGING=info # or 1 or true or yes [deprecated]
|
205
|
+
export LISTEN_GEM_DEBUGGING=warn
|
206
|
+
export LISTEN_GEM_DEBUGGING=fatal
|
207
|
+
export LISTEN_GEM_DEBUGGING=error
|
208
|
+
```
|
209
|
+
The default of `error` will be used if an unsupported value is set.
|
176
210
|
|
177
|
-
|
211
|
+
Note: The alternate values `1`, `2`, `true` and `yes` shown above are deprecated and will be removed from `listen` v4.0.
|
178
212
|
|
179
|
-
|
213
|
+
### Disabling Logging
|
214
|
+
If you want to disable `listen` logging, set
|
215
|
+
```
|
216
|
+
Listen.logger = ::Logger.new('/dev/null')
|
217
|
+
```
|
218
|
+
## Listen Adapters
|
219
|
+
|
220
|
+
The `Listen` gem has a set of adapters to notify it when there are changes.
|
180
221
|
|
181
222
|
There are 4 OS-specific adapters to support Darwin, Linux, \*BSD and Windows.
|
182
223
|
These adapters are fast as they use some system-calls to implement the notifying function.
|
@@ -184,9 +225,9 @@ These adapters are fast as they use some system-calls to implement the notifying
|
|
184
225
|
There is also a polling adapter - although it's much slower than other adapters,
|
185
226
|
it works on every platform/system and scenario (including network filesystems such as VM shared folders).
|
186
227
|
|
187
|
-
The Darwin and Linux adapters are dependencies of the
|
228
|
+
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.
|
188
229
|
|
189
|
-
The
|
230
|
+
The `listen` gem will choose the best adapter automatically, if present. If you
|
190
231
|
want to force the use of the polling adapter, use the `:force_polling` option
|
191
232
|
while initializing the listener.
|
192
233
|
|
@@ -197,7 +238,7 @@ If you are on Windows, it's recommended to use the [`wdm`](https://github.com/Ma
|
|
197
238
|
Please add the following to your Gemfile:
|
198
239
|
|
199
240
|
```ruby
|
200
|
-
gem 'wdm', '>= 0.1.0'
|
241
|
+
gem 'wdm', '>= 0.1.0', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
|
201
242
|
```
|
202
243
|
|
203
244
|
### On \*BSD
|
@@ -216,35 +257,144 @@ end
|
|
216
257
|
|
217
258
|
### Getting the [polling fallback message](#options)?
|
218
259
|
|
219
|
-
|
260
|
+
If you see:
|
261
|
+
```
|
262
|
+
Listen will be polling for changes.
|
263
|
+
```
|
264
|
+
|
265
|
+
This means the Listen gem can’t find an optimized adapter. Typically this is caused by:
|
266
|
+
|
267
|
+
- You’re on Windows and WDM gem isn’t installed.
|
268
|
+
- You’re running the app without Bundler or RubyGems.
|
269
|
+
- Using Sass which includes an ancient (the “dinosaur” type of ancient) version of the Listen gem.
|
270
|
+
|
271
|
+
Possible solutions:
|
220
272
|
|
221
|
-
|
273
|
+
1. Suppress the message by using the :force_polling option. Or, you could just ignore the message since it’s harmless.
|
274
|
+
2. Windows users: Install the WDM gem.
|
275
|
+
3. Upgrade Ruby (use RubyInstaller for Windows or RVM/rbenv for Mac) and RubyGems.
|
276
|
+
3. Run your apps using Bundler.
|
277
|
+
4. Sass users: Install the latest version of Listen and try again.
|
278
|
+
|
279
|
+
#### Simplified Bundler and Sass example
|
280
|
+
Create a Gemfile with these lines:
|
281
|
+
```
|
282
|
+
source 'https://rubygems.org'
|
283
|
+
gem 'listen'
|
284
|
+
gem 'sass'
|
285
|
+
```
|
286
|
+
Next, use Bundler to update gems:
|
287
|
+
```
|
288
|
+
$ bundle update
|
289
|
+
$ bundle exec sass --watch # ... or whatever app is using Listen.
|
290
|
+
```
|
222
291
|
|
223
|
-
|
292
|
+
### Increasing the amount of inotify watchers
|
224
293
|
|
225
|
-
|
294
|
+
If you are running Debian, RedHat, or another similar Linux distribution, run the following in a terminal:
|
295
|
+
```
|
296
|
+
$ sudo sh -c "echo fs.inotify.max_user_watches=524288 >> /etc/sysctl.conf"
|
297
|
+
$ sudo sysctl -p
|
298
|
+
```
|
299
|
+
If you are running ArchLinux, search the `/etc/sysctl.d/` directory for config files with the setting:
|
300
|
+
```
|
301
|
+
$ grep -H -s "fs.inotify.max_user_watches" /etc/sysctl.d/*
|
302
|
+
/etc/sysctl.d/40-max_user_watches.conf:fs.inotify.max_user_watches=100000
|
303
|
+
```
|
304
|
+
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):
|
305
|
+
```
|
306
|
+
$ sudo sh -c "echo fs.inotify.max_user_watches=524288 > /etc/sysctl.d/40-max-user-watches.conf"
|
307
|
+
$ sudo sysctl --system
|
308
|
+
```
|
309
|
+
|
310
|
+
#### The technical details
|
311
|
+
Listen uses `inotify` by default on Linux to monitor directories for changes.
|
312
|
+
It's not uncommon to encounter a system limit on the number of files you can monitor.
|
313
|
+
For example, Ubuntu Lucid's (64bit) `inotify` limit is set to 8192.
|
314
|
+
|
315
|
+
You can get your current inotify file watch limit by executing:
|
316
|
+
```
|
317
|
+
$ cat /proc/sys/fs/inotify/max_user_watches
|
318
|
+
```
|
319
|
+
When this limit is not enough to monitor all files inside a directory, the limit must be increased for Listen to work properly.
|
320
|
+
|
321
|
+
You can set a new limit temporarily with:
|
322
|
+
```
|
323
|
+
$ sudo sysctl fs.inotify.max_user_watches=524288
|
324
|
+
$ sudo sysctl -p
|
325
|
+
```
|
326
|
+
If you like to make your limit permanent, use:
|
327
|
+
```
|
328
|
+
$ sudo sh -c "echo fs.inotify.max_user_watches=524288 >> /etc/sysctl.conf"
|
329
|
+
$ sudo sysctl -p
|
330
|
+
```
|
331
|
+
You may also need to pay attention to the values of `max_queued_events` and `max_user_instances` if Listen keeps on complaining.
|
332
|
+
|
333
|
+
#### More info
|
334
|
+
Man page for [inotify(7)](https://linux.die.net/man/7/inotify).
|
335
|
+
Blog post: [limit of inotify](https://blog.sorah.jp/2012/01/24/inotify-limitation).
|
336
|
+
|
337
|
+
### Issues and Troubleshooting
|
338
|
+
|
339
|
+
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).
|
340
|
+
|
341
|
+
*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.*
|
342
|
+
|
343
|
+
#### 3 steps before you start diagnosing problems
|
344
|
+
These 3 steps will:
|
345
|
+
|
346
|
+
- help quickly troubleshoot obscure problems (trust me, most of them are obscure)
|
347
|
+
- help quickly identify the area of the problem (a full list is below)
|
348
|
+
- help you get familiar with listen's diagnostic mode (it really comes in handy, trust me)
|
349
|
+
- help you create relevant output before you submit an issue (so we can respond with answers instead of tons of questions)
|
350
|
+
|
351
|
+
Step 1 - The most important option in Listen
|
352
|
+
For effective troubleshooting set the `LISTEN_GEM_DEBUGGING=info` variable before starting `listen`.
|
353
|
+
|
354
|
+
Step 2 - Verify polling works
|
355
|
+
Polling has to work ... or something is really wrong (and we need to know that before anything else).
|
356
|
+
|
357
|
+
(see force_polling option).
|
358
|
+
|
359
|
+
After starting `listen`, you should see something like:
|
360
|
+
```
|
361
|
+
INFO -- : Record.build(): 0.06773114204406738 seconds
|
362
|
+
```
|
363
|
+
Step 3 - Trigger some changes directly without using editors or apps
|
364
|
+
Make changes e.g. touch foo or echo "a" >> foo (for troubleshooting, avoid using an editor which could generate too many misleading events).
|
365
|
+
|
366
|
+
You should see something like:
|
367
|
+
```
|
368
|
+
INFO -- : listen: raw changes: [[:added, "/home/me/foo"]]
|
369
|
+
INFO -- : listen: final changes: {:modified=>[], :added=>["/home/me/foo"], :removed=>[]}
|
370
|
+
```
|
371
|
+
"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).
|
226
372
|
|
227
373
|
## Performance
|
228
374
|
|
229
|
-
If
|
375
|
+
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).
|
230
376
|
|
231
377
|
Also, if the directories you're watching contain many files, make sure you're:
|
232
378
|
|
233
379
|
* not using Polling (ideally)
|
234
380
|
* using `:ignore` and `:only` options to avoid tracking directories you don't care about (important with Polling and on MacOS)
|
235
|
-
* running
|
381
|
+
* running `listen` with the `:latency` and `:wait_for_delay` options not too small or too big (depends on needs)
|
236
382
|
* not watching directories with log files, database files or other frequently changing files
|
237
|
-
* not using a version of
|
238
|
-
* not getting silent crashes within
|
239
|
-
* not running multiple instances of
|
383
|
+
* not using a version of `listen` prior to 2.7.7
|
384
|
+
* not getting silent crashes within `listen` (see `LISTEN_GEM_DEBUGGING=debug`)
|
385
|
+
* not running multiple instances of `listen` in the background
|
240
386
|
* using a file system with atime modification disabled (ideally)
|
241
387
|
* not using a filesystem with inaccurate file modification times (ideally), e.g. HFS, VFAT
|
242
388
|
* not buffering to a slow terminal (e.g. transparency + fancy font + slow gfx card + lots of output)
|
243
389
|
* ideally not running a slow encryption stack, e.g. btrfs + ecryptfs
|
244
390
|
|
245
|
-
When in doubt, LISTEN_GEM_DEBUGGING=
|
391
|
+
When in doubt, `LISTEN_GEM_DEBUGGING=debug` can help discover the actual events and time they happened.
|
246
392
|
|
247
|
-
|
393
|
+
## Tips and Techniques
|
394
|
+
- Watch only directories you're interested in.
|
395
|
+
- Set your editor to save quickly (e.g. without backup files, without atomic-save)
|
396
|
+
- Tweak the `:latency` and `:wait_for_delay` options until you get good results (see [options](#options)).
|
397
|
+
- Add `:ignore` rules to silence all events you don't care about (reduces a lot of noise, especially if you use it on directories)
|
248
398
|
|
249
399
|
## Development
|
250
400
|
|
data/bin/listen
CHANGED
@@ -1,12 +1,11 @@
|
|
1
1
|
#!/usr/bin/env ruby
|
2
|
+
# frozen_string_literal: true
|
2
3
|
|
3
4
|
require 'listen'
|
4
5
|
require 'listen/cli'
|
5
6
|
|
6
|
-
|
7
|
-
|
8
|
-
Signal.trap('INT') { Thread.new { Listen.stop } }
|
9
|
-
end
|
7
|
+
if !defined?(JRUBY_VERSION) && Signal.list.keys.include?('INT')
|
8
|
+
Signal.trap('INT') { Thread.new { Listen.stop } }
|
10
9
|
end
|
11
10
|
|
12
11
|
Listen::CLI.start
|