listen 3.1.5 → 3.7.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 7386f68792e7b45304769943823e31ad245b400d
4
- data.tar.gz: f199b345bccc4a716fe87fa703c9aea864a25d17
2
+ SHA256:
3
+ metadata.gz: ff9bdc7fe6e17c76745c2bd710f79322f22ebd7f7274241403f4132a575d2a7a
4
+ data.tar.gz: 3868e870e71badf618acb9f50a6d36227f722dd592360e894bb7cc9e2b5feb67
5
5
  SHA512:
6
- metadata.gz: 12ad0394d61e54beefef077dfcbf798c2b358ed56f0c8cf3e5d57df015623d6f823f7346f88463d6d7ce3a6845dff19fb2e3538030911050b68f9153cd43d72b
7
- data.tar.gz: ef7151a3ce30aa79ae408eb22c2e455b418229e3fce9c4584b0a1a1c913c34235661cd72e94802b811b624c01ecb04ce6b9c5814aafa0810a233ecd7e900e7ff
6
+ metadata.gz: dbdddb8b8196ed73ae3e23c1bcea1396451bfd2fa36524778bbfbb98dc4565fd248d9035226c286c9feab1b92fddc61c2f0903159c8b4717c9983c535a06da70
7
+ data.tar.gz: 9942df50a62c7a88fafe9eea748e611618251db4ca5bf94850585e0529b3c6812f6658c2221c39a7160d72f5f0ce26a207e2fb1feedd404e20a9f0c34365979f
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/wiki/Troubleshooting) for known issues, solutions and workarounds.
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/wiki/Troubleshooting) for details.
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
@@ -31,8 +31,15 @@ Pull requests are very welcome! Please try to follow these simple rules if appli
31
31
  * Make sure your patches are well tested. All specs run with `rake spec` must pass.
32
32
  * Update the [Yard](http://yardoc.org/) documentation.
33
33
  * Update the [README](https://github.com/guard/listen/blob/master/README.md).
34
- * Update the [CHANGELOG](https://github.com/guard/listen/blob/master/CHANGELOG.md) for noteworthy changes.
35
34
  * Please **do not change** the version number.
36
35
 
36
+ The title of your PR will automatically be included in the release notes for the next version of the gem. A maintainer can add one of the following GitHub labels to the PR to automatically categorize it when the release notes are generated:
37
+
38
+ - ⚠️ Breaking
39
+ - ✨ Feature
40
+ - 🐛 Bug Fix
41
+ - 📚 Docs
42
+ - 🏠 Housekeeping
43
+
37
44
  For questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
38
45
  `#guard` (irc.freenode.net).
data/README.md CHANGED
@@ -1,14 +1,11 @@
1
- ## IMPORTANT: [Ruby 2.1 is officially outdated and unsupported!](https://www.ruby-lang.org/en/news/2016/03/30/ruby-2-1-9-released/) Please upgrade to Ruby 2.2 before installing Listen!
2
-
3
- ### (To install for older versions, update Bundler to a prerelease version: `gem install bundler --pre` and Bundler should correctly resolve to an earlier gems for your given Ruby version).
4
-
5
- :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.
6
-
7
1
  # Listen
8
2
 
9
- [![Gem Version](https://badge.fury.io/rb/listen.png)](http://badge.fury.io/rb/listen) [![Build Status](https://travis-ci.org/guard/listen.png)](https://travis-ci.org/guard/listen) [![Dependency Status](https://gemnasium.com/guard/listen.png)](https://gemnasium.com/guard/listen) [![Code Climate](https://codeclimate.com/github/guard/listen.png)](https://codeclimate.com/github/guard/listen) [![Coverage Status](https://coveralls.io/repos/guard/listen/badge.png?branch=master)](https://coveralls.io/r/guard/listen)
3
+ The `listen` gem listens to file modifications and notifies you about the changes.
10
4
 
11
- The Listen gem listens to file modifications and notifies you about the changes.
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)
12
9
 
13
10
  ## Features
14
11
 
@@ -17,45 +14,88 @@ The Listen gem listens to file modifications and notifies you about the changes.
17
14
  * You can watch multiple directories.
18
15
  * Regexp-patterns for ignoring paths for more accuracy and speed
19
16
  * Increased change detection accuracy on OS X HFS and VFAT volumes.
20
- * Tested on selected Ruby environments via [Travis CI](https://travis-ci.org/guard/listen). (See [.travis.yml](https:///github.com/guard/listen/master/.travis.yml) for supported/tested Ruby Versions),
17
+ * Continuous Integration: tested on selected Ruby environments via [Github Workflows](https:///github.com/guard/listen/master/.github/workflows).
21
18
 
22
19
  ## Issues / limitations
23
20
 
24
21
  * Limited support for symlinked directories ([#279](https://github.com/guard/listen/issues/279)):
25
22
  * Symlinks are always followed ([#25](https://github.com/guard/listen/issues/25)).
26
- * 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)).
23
+ * Symlinked directories pointing within a watched directory are not supported ([#273](https://github.com/guard/listen/pull/273).
27
24
  * No directory/adapter-specific configuration options.
28
25
  * Support for plugins planned for future.
29
- * 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'`.
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'`.
30
27
  * Some filesystems won't work without polling (VM/Vagrant Shared folders, NFS, Samba, sshfs, etc.).
31
- * Specs suite on JRuby and Rubinius aren't reliable on Travis CI, but should work.
32
28
  * Windows and \*BSD adapter aren't continuously and automatically tested.
33
29
  * OSX adapter has some performance limitations ([#342](https://github.com/guard/listen/issues/342)).
34
- * Ruby < 2.2.x is no longer supported - upgrade to Ruby 2.2 or 2.3
30
+ * 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).
35
31
 
36
32
  Pull requests or help is very welcome for these.
37
33
 
38
34
  ## Install
39
35
 
40
- The simplest way to install Listen is to use [Bundler](http://bundler.io).
36
+ The simplest way to install `listen` is to use [Bundler](http://bundler.io).
37
+
38
+ ```ruby
39
+ gem 'listen'
40
+ ```
41
41
 
42
+ ## Complete Example
43
+ Here is a complete example of using the `listen` gem:
42
44
  ```ruby
43
- gem 'listen', '~> 3.0' # NOTE: for TCP functionality, use '~> 2.10' for now
45
+ require 'listen'
46
+
47
+ listener = Listen.to('/srv/app') do |modified, added, removed|
48
+ puts(modified: modified, added: added, removed: removed)
49
+ end
50
+ listener.start
51
+ sleep
52
+ ```
53
+ Running the above in the background, you can see the callback block being called in response to each command:
54
+ ```
55
+ $ cd /srv/app
56
+ $ touch a.txt
57
+ {:modified=>[], :added=>["/srv/app/a.txt"], :removed=>[]}
58
+
59
+ $ echo more >> a.txt
60
+ {:modified=>["/srv/app/a.txt"], :added=>[], :removed=>[]}
61
+
62
+ $ mv a.txt b.txt
63
+ {:modified=>[], :added=>["/srv/app/b.txt"], :removed=>["/srv/app/a.txt"]}
64
+
65
+ $ vi b.txt
66
+ # add a line to this new file and press ZZ to save and exit
67
+ {:modified=>["/srv/app/b.txt"], :added=>[], :removed=>[]}
68
+
69
+ $ vi c.txt
70
+ # add a line and press ZZ to save and exit
71
+ {:modified=>[], :added=>["/srv/app/c.txt"], :removed=>[]}
72
+
73
+ $ rm b.txt c.txt
74
+ {:modified=>[], :added=>[], :removed=>["/srv/app/b.txt", "/srv/app/c.txt"]}
44
75
  ```
45
76
 
46
77
  ## Usage
47
78
 
48
- Call `Listen.to` with either a single directory or multiple directories, then define the "changes" callback in a block.
79
+ Call `Listen.to` with one or more directories and the "changes" callback passed as a block.
49
80
 
50
81
  ``` ruby
51
82
  listener = Listen.to('dir/to/listen', 'dir/to/listen2') do |modified, added, removed|
52
- puts "modified absolute path: #{modified}"
53
- puts "added absolute path: #{added}"
54
- puts "removed absolute path: #{removed}"
83
+ puts "modified absolute path array: #{modified}"
84
+ puts "added absolute path array: #{added}"
85
+ puts "removed absolute path array: #{removed}"
55
86
  end
56
- listener.start # not blocking
87
+ listener.start # starts a listener thread--does not block
88
+
89
+ # do whatever you want here...just don't exit the process :)
90
+
57
91
  sleep
58
92
  ```
93
+ ## Changes Callback
94
+
95
+ Changes to the listened-to directories are reported by the listener thread in a callback.
96
+ The callback receives **three** array parameters: `modified`, `added` and `removed`, in that order.
97
+ Each of these three is always an array with 0 or more entries.
98
+ Each array entry is an absolute path.
59
99
 
60
100
  ### Pause / unpause / stop
61
101
 
@@ -76,13 +116,14 @@ listener.unpause # resumes processing changes ("start" would do the same)
76
116
  listener.stop # stop both listening to changes and processing them
77
117
  ```
78
118
 
79
- Note: While paused, Listen keeps on collecting changes in the background - to clear them, call "stop"
119
+ Note: While paused, `listen` keeps on collecting changes in the background - to clear them, call `stop`.
80
120
 
81
- Note: You should keep track of all started listeners and stop them properly on finish.
121
+ Note: You should keep track of all started listeners and `stop` them properly on finish.
82
122
 
83
123
  ### Ignore / ignore!
84
124
 
85
- Listen ignores some directories and extensions by default (See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer), you can add ignoring patterns with the `ignore` option/method or overwrite default with `ignore!` option/method.
125
+ `Listen` ignores some directories and extensions by default (See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer).
126
+ You can add ignoring patterns with the `ignore` option/method or overwrite default with `ignore!` option/method.
86
127
 
87
128
  ``` ruby
88
129
  listener = Listen.to('dir/path/to/listen', ignore: /\.txt/) { |modified, added, removed| # ... }
@@ -94,11 +135,11 @@ sleep
94
135
 
95
136
  Note: `:ignore` regexp patterns are evaluated against relative paths.
96
137
 
97
- Note: Ignoring paths does not improve performance, except when Polling ([#274](https://github.com/guard/listen/issues/274))
138
+ Note: Ignoring paths does not improve performance, except when Polling ([#274](https://github.com/guard/listen/issues/274)).
98
139
 
99
140
  ### Only
100
141
 
101
- Listen catches 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.
142
+ `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.
102
143
 
103
144
  ``` ruby
104
145
  listener = Listen.to('dir/path/to/listen', only: /\.rb$/) { |modified, added, removed| # ... }
@@ -110,35 +151,6 @@ sleep
110
151
  Note: `:only` regexp patterns are evaluated only against relative **file** paths.
111
152
 
112
153
 
113
- ## Changes callback
114
-
115
- Changes to the listened-to directories gets reported back to the user in a callback.
116
- The registered callback gets invoked, when there are changes, with **three** parameters:
117
- `modified`, `added` and `removed` paths, in that particular order.
118
- Paths are always returned in their absolute form.
119
-
120
- Example:
121
-
122
- ```ruby
123
- listener = Listen.to('path/to/app') do |modified, added, removed|
124
- # This block will be called when there are changes.
125
- end
126
- listener.start
127
- sleep
128
- ```
129
-
130
- or ...
131
-
132
- ```ruby
133
- # Create a callback
134
- callback = Proc.new do |modified, added, removed|
135
- # This proc will be called when there are changes.
136
- end
137
- listener = Listen.to('dir', &callback)
138
- listener.start
139
- sleep
140
- ```
141
-
142
154
  ## Options
143
155
 
144
156
  All the following options can be set through the `Listen.to` after the directory path(s) params.
@@ -168,16 +180,42 @@ polling_fallback_message: 'custom message' # Set a custom polling fallback
168
180
  # default: "Listen will be polling for changes. Learn more at https://github.com/guard/listen#listen-adapters."
169
181
  ```
170
182
 
171
- ## Debugging
183
+ ## Logging and Debugging
172
184
 
173
- Setting the environment variable `LISTEN_GEM_DEBUGGING=1` sets up the INFO level logger, while `LISTEN_GEM_DEBUGGING=2` sets up the DEBUG level logger.
185
+ `Listen` logs its activity to `Listen.logger`.
186
+ This is the primary method of debugging.
174
187
 
175
- You can also set `Listen.logger` to a custom logger.
188
+ ### Custom Logger
189
+ You can call `Listen.logger =` to set a custom `listen` logger for the process. For example:
190
+ ```
191
+ Listen.logger = Rails.logger
192
+ ```
176
193
 
194
+ ### Default Logger
195
+ If no custom logger is set, a default `listen` logger which logs to to `STDERR` will be created and assigned to `Listen.logger`.
177
196
 
178
- ## Listen adapters
197
+ The default logger defaults to the `error` logging level (severity).
198
+ You can override the logging level by setting the environment variable `LISTEN_GEM_DEBUGGING=<level>`.
199
+ For `<level>`, all standard `::Logger` levels are supported, with any mix of upper-/lower-case:
200
+ ```
201
+ export LISTEN_GEM_DEBUGGING=debug # or 2 [deprecated]
202
+ export LISTEN_GEM_DEBUGGING=info # or 1 or true or yes [deprecated]
203
+ export LISTEN_GEM_DEBUGGING=warn
204
+ export LISTEN_GEM_DEBUGGING=fatal
205
+ export LISTEN_GEM_DEBUGGING=error
206
+ ```
207
+ The default of `error` will be used if an unsupported value is set.
179
208
 
180
- The Listen gem has a set of adapters to notify it when there are changes.
209
+ Note: The alternate values `1`, `2`, `true` and `yes` shown above are deprecated and will be removed from `listen` v4.0.
210
+
211
+ ### Disabling Logging
212
+ If you want to disable `listen` logging, set
213
+ ```
214
+ Listen.logger = ::Logger.new('/dev/null')
215
+ ```
216
+ ## Listen Adapters
217
+
218
+ The `Listen` gem has a set of adapters to notify it when there are changes.
181
219
 
182
220
  There are 4 OS-specific adapters to support Darwin, Linux, \*BSD and Windows.
183
221
  These adapters are fast as they use some system-calls to implement the notifying function.
@@ -185,9 +223,9 @@ These adapters are fast as they use some system-calls to implement the notifying
185
223
  There is also a polling adapter - although it's much slower than other adapters,
186
224
  it works on every platform/system and scenario (including network filesystems such as VM shared folders).
187
225
 
188
- 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.
226
+ 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.
189
227
 
190
- The Listen gem will choose the best adapter automatically, if present. If you
228
+ The `listen` gem will choose the best adapter automatically, if present. If you
191
229
  want to force the use of the polling adapter, use the `:force_polling` option
192
230
  while initializing the listener.
193
231
 
@@ -198,7 +236,7 @@ If you are on Windows, it's recommended to use the [`wdm`](https://github.com/Ma
198
236
  Please add the following to your Gemfile:
199
237
 
200
238
  ```ruby
201
- gem 'wdm', '>= 0.1.0' if Gem.win_platform?
239
+ gem 'wdm', '>= 0.1.0', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
202
240
  ```
203
241
 
204
242
  ### On \*BSD
@@ -217,35 +255,144 @@ end
217
255
 
218
256
  ### Getting the [polling fallback message](#options)?
219
257
 
220
- Please visit the [installation section of the Listen WIKI](https://github.com/guard/listen/wiki#installation) for more information and options for potential fixes.
258
+ If you see:
259
+ ```
260
+ Listen will be polling for changes.
261
+ ```
262
+
263
+ This means the Listen gem can’t find an optimized adapter. Typically this is caused by:
264
+
265
+ - You’re on Windows and WDM gem isn’t installed.
266
+ - You’re running the app without Bundler or RubyGems.
267
+ - Using Sass which includes an ancient (the “dinosaur” type of ancient) version of the Listen gem.
268
+
269
+ Possible solutions:
270
+
271
+ 1. Suppress the message by using the :force_polling option. Or, you could just ignore the message since it’s harmless.
272
+ 2. Windows users: Install the WDM gem.
273
+ 3. Upgrade Ruby (use RubyInstaller for Windows or RVM/rbenv for Mac) and RubyGems.
274
+ 3. Run your apps using Bundler.
275
+ 4. Sass users: Install the latest version of Listen and try again.
276
+
277
+ #### Simplified Bundler and Sass example
278
+ Create a Gemfile with these lines:
279
+ ```
280
+ source 'https://rubygems.org'
281
+ gem 'listen'
282
+ gem 'sass'
283
+ ```
284
+ Next, use Bundler to update gems:
285
+ ```
286
+ $ bundle update
287
+ $ bundle exec sass --watch # ... or whatever app is using Listen.
288
+ ```
289
+
290
+ ### Increasing the amount of inotify watchers
291
+
292
+ If you are running Debian, RedHat, or another similar Linux distribution, run the following in a terminal:
293
+ ```
294
+ $ sudo sh -c "echo fs.inotify.max_user_watches=524288 >> /etc/sysctl.conf"
295
+ $ sudo sysctl -p
296
+ ```
297
+ If you are running ArchLinux, search the `/etc/sysctl.d/` directory for config files with the setting:
298
+ ```
299
+ $ grep -H -s "fs.inotify.max_user_watches" /etc/sysctl.d/*
300
+ /etc/sysctl.d/40-max_user_watches.conf:fs.inotify.max_user_watches=100000
301
+ ```
302
+ 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):
303
+ ```
304
+ $ sudo sh -c "echo fs.inotify.max_user_watches=524288 > /etc/sysctl.d/40-max-user-watches.conf"
305
+ $ sudo sysctl --system
306
+ ```
307
+
308
+ #### The technical details
309
+ Listen uses `inotify` by default on Linux to monitor directories for changes.
310
+ It's not uncommon to encounter a system limit on the number of files you can monitor.
311
+ For example, Ubuntu Lucid's (64bit) `inotify` limit is set to 8192.
312
+
313
+ You can get your current inotify file watch limit by executing:
314
+ ```
315
+ $ cat /proc/sys/fs/inotify/max_user_watches
316
+ ```
317
+ When this limit is not enough to monitor all files inside a directory, the limit must be increased for Listen to work properly.
221
318
 
222
- ### Issues and troubleshooting
319
+ You can set a new limit temporarily with:
320
+ ```
321
+ $ sudo sysctl fs.inotify.max_user_watches=524288
322
+ $ sudo sysctl -p
323
+ ```
324
+ If you like to make your limit permanent, use:
325
+ ```
326
+ $ sudo sh -c "echo fs.inotify.max_user_watches=524288 >> /etc/sysctl.conf"
327
+ $ sudo sysctl -p
328
+ ```
329
+ You may also need to pay attention to the values of `max_queued_events` and `max_user_instances` if Listen keeps on complaining.
330
+
331
+ #### More info
332
+ Man page for [inotify(7)](https://linux.die.net/man/7/inotify).
333
+ Blog post: [limit of inotify](https://blog.sorah.jp/2012/01/24/inotify-limitation).
334
+
335
+ ### Issues and Troubleshooting
336
+
337
+ 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).
338
+
339
+ *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.*
340
+
341
+ #### 3 steps before you start diagnosing problems
342
+ These 3 steps will:
343
+
344
+ - help quickly troubleshoot obscure problems (trust me, most of them are obscure)
345
+ - help quickly identify the area of the problem (a full list is below)
346
+ - help you get familiar with listen's diagnostic mode (it really comes in handy, trust me)
347
+ - help you create relevant output before you submit an issue (so we can respond with answers instead of tons of questions)
348
+
349
+ Step 1 - The most important option in Listen
350
+ For effective troubleshooting set the `LISTEN_GEM_DEBUGGING=info` variable before starting `listen`.
223
351
 
224
- *NOTE: without providing the output after setting the `LISTEN_GEM_DEBUGGING=1` environment variable, it can be almost impossible to guess why listen is not working as expected.*
352
+ Step 2 - Verify polling works
353
+ Polling has to work ... or something is really wrong (and we need to know that before anything else).
225
354
 
226
- See [TROUBLESHOOTING](https://github.com/guard/listen/wiki/Troubleshooting)
355
+ (see force_polling option).
356
+
357
+ After starting `listen`, you should see something like:
358
+ ```
359
+ INFO -- : Record.build(): 0.06773114204406738 seconds
360
+ ```
361
+ Step 3 - Trigger some changes directly without using editors or apps
362
+ Make changes e.g. touch foo or echo "a" >> foo (for troubleshooting, avoid using an editor which could generate too many misleading events).
363
+
364
+ You should see something like:
365
+ ```
366
+ INFO -- : listen: raw changes: [[:added, "/home/me/foo"]]
367
+ INFO -- : listen: final changes: {:modified=>[], :added=>["/home/me/foo"], :removed=>[]}
368
+ ```
369
+ "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).
227
370
 
228
371
  ## Performance
229
372
 
230
- 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).
373
+ 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).
231
374
 
232
375
  Also, if the directories you're watching contain many files, make sure you're:
233
376
 
234
377
  * not using Polling (ideally)
235
378
  * using `:ignore` and `:only` options to avoid tracking directories you don't care about (important with Polling and on MacOS)
236
- * running Listen with the `:latency` and `:wait_for_delay` options not too small or too big (depends on needs)
379
+ * running `listen` with the `:latency` and `:wait_for_delay` options not too small or too big (depends on needs)
237
380
  * not watching directories with log files, database files or other frequently changing files
238
- * not using a version of Listen prior to 2.7.7
239
- * not getting silent crashes within Listen (see LISTEN_GEM_DEBUGGING=2)
240
- * not running multiple instances of Listen in the background
381
+ * not using a version of `listen` prior to 2.7.7
382
+ * not getting silent crashes within `listen` (see `LISTEN_GEM_DEBUGGING=debug`)
383
+ * not running multiple instances of `listen` in the background
241
384
  * using a file system with atime modification disabled (ideally)
242
385
  * not using a filesystem with inaccurate file modification times (ideally), e.g. HFS, VFAT
243
386
  * not buffering to a slow terminal (e.g. transparency + fancy font + slow gfx card + lots of output)
244
387
  * ideally not running a slow encryption stack, e.g. btrfs + ecryptfs
245
388
 
246
- When in doubt, LISTEN_GEM_DEBUGGING=2 can help discover the actual events and time they happened.
389
+ When in doubt, `LISTEN_GEM_DEBUGGING=debug` can help discover the actual events and time they happened.
247
390
 
248
- See also [Tips and Techniques](https://github.com/guard/listen/wiki/Tips-and-Techniques).
391
+ ## Tips and Techniques
392
+ - Watch only directories you're interested in.
393
+ - Set your editor to save quickly (e.g. without backup files, without atomic-save)
394
+ - Tweak the `:latency` and `:wait_for_delay` options until you get good results (see [options](#options)).
395
+ - Add `:ignore` rules to silence all events you don't care about (reduces a lot of noise, especially if you use it on directories)
249
396
 
250
397
  ## Development
251
398
 
@@ -263,11 +410,29 @@ Pull requests are very welcome! Please try to follow these simple rules if appli
263
410
  For questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
264
411
  `#guard` (irc.freenode.net).
265
412
 
413
+ ## Releasing
414
+
415
+ ### Prerequisites
416
+
417
+ * You must have commit rights to the GitHub repository.
418
+ * You must have push rights for rubygems.org.
419
+
420
+ ### How to release
421
+
422
+ 1. Run `bundle install` to make sure that you have all the gems necessary for testing and releasing.
423
+ 2. **Ensure all tests are passing by running `bundle exec rake`.**
424
+ 3. Determine which would be the correct next version number according to [semver](http://semver.org/).
425
+ 4. Update the version in `./lib/listen/version.rb`.
426
+ 5. Update the version in the Install section of `./README.md` (`gem 'listen', '~> X.Y'`).
427
+ 6. Commit the version in a single commit, the message should be "Preparing vX.Y.Z"
428
+ 7. Run `bundle exec rake release:full`; this will tag, push to GitHub, and publish to rubygems.org.
429
+ 8. Update and publish the release notes on the [GitHub releases page](https://github.com/guard/listen/releases) if necessary
430
+
266
431
  ## Acknowledgments
267
432
 
268
433
  * [Michael Kessler (netzpirat)][] for having written the [initial specs](https://github.com/guard/listen/commit/1e457b13b1bb8a25d2240428ce5ed488bafbed1f).
269
434
  * [Travis Tilley (ttilley)][] for this awesome work on [fssm][] & [rb-fsevent][].
270
- * [Nathan Weizenbaum (nex3)][] for [rb-inotify][], a thorough inotify wrapper.
435
+ * [Natalie Weizenbaum (nex3)][] for [rb-inotify][], a thorough inotify wrapper.
271
436
  * [Mathieu Arnold (mat813)][] for [rb-kqueue][], a simple kqueue wrapper.
272
437
  * [Maher Sallam][] for [wdm][], windows support wouldn't exist without him.
273
438
  * [Yehuda Katz (wycats)][] for [vigilo][], that has been a great source of inspiration.
@@ -287,7 +452,7 @@ For questions please join us in our [Google group](http://groups.google.com/grou
287
452
  [fssm]: https://github.com/ttilley/fssm
288
453
  [rb-fsevent]: https://github.com/thibaudgg/rb-fsevent
289
454
  [Mathieu Arnold (mat813)]: https://github.com/mat813
290
- [Nathan Weizenbaum (nex3)]: https://github.com/nex3
455
+ [Natalie Weizenbaum (nex3)]: https://github.com/nex3
291
456
  [rb-inotify]: https://github.com/nex3/rb-inotify
292
457
  [stereobooster]: https://github.com/stereobooster
293
458
  [rb-fchange]: https://github.com/stereobooster/rb-fchange
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
- unless defined?(JRUBY_VERSION)
7
- if Signal.list.keys.include?('INT')
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
@@ -1,17 +1,18 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'listen/options'
2
4
  require 'listen/record'
3
5
  require 'listen/change'
6
+ require 'listen/thread'
4
7
 
5
8
  module Listen
6
9
  module Adapter
7
10
  class Base
8
- attr_reader :options
11
+ attr_reader :options, :config
9
12
 
10
13
  # TODO: only used by tests
11
14
  DEFAULTS = {}.freeze
12
15
 
13
- attr_reader :config
14
-
15
16
  def initialize(config)
16
17
  @started = false
17
18
  @config = config
@@ -28,9 +29,10 @@ module Listen
28
29
  end
29
30
 
30
31
  # TODO: it's a separate method as a temporary workaround for tests
32
+ # rubocop:disable Metrics/MethodLength
31
33
  def configure
32
34
  if @configured
33
- _log(:warn, 'Adapter already configured!')
35
+ Listen.logger.warn('Adapter already configured!')
34
36
  return
35
37
  end
36
38
 
@@ -49,11 +51,12 @@ module Listen
49
51
  # TODO: separate config per directory (some day maybe)
50
52
  change_config = Change::Config.new(config.queue, config.silencer)
51
53
  config.directories.each do |dir|
52
- record = Record.new(dir)
54
+ record = Record.new(dir, config.silencer)
53
55
  snapshot = Change.new(change_config, record)
54
56
  @snapshots[dir] = snapshot
55
57
  end
56
58
  end
59
+ # rubocop:enable Metrics/MethodLength
57
60
 
58
61
  def started?
59
62
  @started
@@ -63,48 +66,39 @@ module Listen
63
66
  configure
64
67
 
65
68
  if started?
66
- _log(:warn, 'Adapter already started!')
69
+ Listen.logger.warn('Adapter already started!')
67
70
  return
68
71
  end
69
72
 
70
73
  @started = true
71
74
 
72
- calling_stack = caller.dup
73
- Listen::Internals::ThreadPool.add do
74
- begin
75
- @snapshots.values.each do |snapshot|
76
- _timed('Record.build()') { snapshot.record.build }
77
- end
78
- _run
79
- rescue
80
- msg = 'run() in thread failed: %s:\n'\
81
- ' %s\n\ncalled from:\n %s'
82
- _log_exception(msg, calling_stack)
83
- raise # for unit tests mostly
75
+ @run_thread = Listen::Thread.new("run_thread") do
76
+ @snapshots.each_value do |snapshot|
77
+ _timed('Record.build()') { snapshot.record.build }
84
78
  end
79
+ _run
85
80
  end
86
81
  end
87
82
 
88
83
  def stop
89
84
  _stop
90
- end
91
-
92
- def self.usable?
93
- const_get('OS_REGEXP') =~ RbConfig::CONFIG['target_os']
85
+ config.queue.close # this causes queue.pop to return `nil` to the front-end
94
86
  end
95
87
 
96
88
  private
97
89
 
98
90
  def _stop
91
+ @run_thread&.kill
92
+ @run_thread = nil
99
93
  end
100
94
 
101
95
  def _timed(title)
102
- start = Time.now.to_f
96
+ start = MonotonicTime.now
103
97
  yield
104
- diff = Time.now.to_f - start
105
- Listen::Logger.info format('%s: %.05f seconds', title, diff)
98
+ diff = MonotonicTime.now - start
99
+ Listen.logger.info format('%s: %.05f seconds', title, diff)
106
100
  rescue
107
- Listen::Logger.warn "#{title} crashed: #{$ERROR_INFO.inspect}"
101
+ Listen.logger.warn "#{title} crashed: #{$ERROR_INFO.inspect}"
108
102
  raise
109
103
  end
110
104
 
@@ -114,10 +108,6 @@ module Listen
114
108
  @snapshots[dir].invalidate(type, rel_path, options)
115
109
  end
116
110
 
117
- def _log(*args, &block)
118
- self.class.send(:_log, *args, &block)
119
- end
120
-
121
111
  def _log_exception(msg, caller_stack)
122
112
  formatted = format(
123
113
  msg,
@@ -126,14 +116,12 @@ module Listen
126
116
  caller_stack * "\n"
127
117
  )
128
118
 
129
- _log(:error, formatted)
119
+ Listen.logger.error(formatted)
130
120
  end
131
121
 
132
122
  class << self
133
- private
134
-
135
- def _log(*args, &block)
136
- Listen::Logger.send(*args, &block)
123
+ def usable?
124
+ const_get('OS_REGEXP') =~ RbConfig::CONFIG['target_os']
137
125
  end
138
126
  end
139
127
  end