listen 1.3.1 → 2.0.0.beta.1

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
2
  SHA1:
3
- metadata.gz: d9b4d00e44252c4d2c28d7b1d1032789dda96247
4
- data.tar.gz: 3040790b24b6f3020fdf68b3f86eaf9bdffc0f7b
3
+ metadata.gz: e5eb3d853fcddc242d96e4e0295b3966b6349119
4
+ data.tar.gz: aa33f0a0e2d623d76027f758b78463ae2c052573
5
5
  SHA512:
6
- metadata.gz: 19395a1831d03b0f76627e4343d0baa9611a2a7f2a89b5d28aaeadae555cdb6a3518a6f7e9be2fb6dcc0d3e4ab8d6c804742ee529f65c8a756ff30507e3f1ded
7
- data.tar.gz: fd612f0cb477281402c7b95cad3681f813be231b7b098d81bbfb5c7f92ae3fbf87b8f18b774047ef308b4ee0feb77644f2a61453315fced0387f8ea80d605b31
6
+ metadata.gz: ce58ba37a3bdee68cb69dcff3b3a583dec582cb1ccb680e81c6e14d33fea0d5a0d99fcf16e4346c91d56786d31f0e694c671c52de3eab4269e48409bfce3d3c5
7
+ data.tar.gz: 9e6856329957aeedb9415eaf26255b373ff60d288128bd82a2ca8cbd9c7e9fe075a74c055e0ddcb7afd6fc68d6781262c94d7bde8005e6b0a765834e1ce79ec0
data/CHANGELOG.md CHANGED
@@ -1,368 +1 @@
1
- # !!! CHANGELOG moved to Github [releases](https://github.com/guard/listen/releases) page !!!
2
-
3
-
4
- ## 1.2.2 - Jun 17, 2013
5
-
6
- ### Bug fix
7
-
8
- - Rescue all error on sha1_checksum generation. ([@thibaudgg][])
9
-
10
- ## 1.2.1 - Jun 11, 2013
11
-
12
- ### Improvement
13
-
14
- - Ignore 'bundle' folder by default. ([@thibaudgg][])
15
-
16
- ## 1.2.0 - Jun 11, 2013
17
-
18
- ### Improvement
19
-
20
- - [#124][] New `force_adapter` option, skip the `.listen_test` adapter test. ([@nicobrevin][])
21
-
22
- ## 1.1.6 - Jun 4, 2013
23
-
24
- ### Change
25
-
26
- - [#120][] Warn when using relative_paths option when listening to multiple diretories. (reported by [@chriseppstein][], added by [@thibaudgg][])
27
-
28
- ## 1.1.5 - Jun 3, 2013
29
-
30
- ### Bug fix
31
-
32
- - [#122][] Fix stop called very soon after starting. (reported by [@chriseppstein][], fixed by [@thibaudgg][])
33
-
34
- ## 1.1.4 - May 28, 2013
35
-
36
- ### Bug fix
37
-
38
- - [#118][] Prevent polling just because the adapter gem was already required. ([@nilbus][])
39
-
40
- ## 1.1.3 - May 21, 2013
41
-
42
- ### Bug fix
43
-
44
- - [#117][] Fix jruby error on Pathname#relative_path_from. ([@luikore][])
45
-
46
- ## 1.1.2 - May 14, 2013
47
-
48
- ### Bug fix
49
-
50
- - [#115][] Fix for directory containing non-ascii chars. ([@luikore][])
51
-
52
- ## 1.1.1 - May 14, 2013
53
-
54
- ### Bug fix
55
-
56
- - [#113][] Kill poller_thread before waiting for it to die. ([@antifuchs][])
57
-
58
- ## 1.1.0 - May 11, 2013
59
-
60
- ### Bug fix
61
-
62
- - [#112][] Expand path for the given directories. (reported by [@nex3][], fixed by [@thibaudgg][])
63
-
64
- ### Change
65
-
66
- - [#110][] Remove MultiListener deprecation warning message. (reported by [@nex3][], fixed by [@thibaudgg][])
67
-
68
- ## 1.0.3 - April 29, 2013
69
-
70
- ### Bug fix
71
-
72
- - Rescue Errno::EBADF on sha1_checksum generation. ([@thibaudgg][])
73
-
74
- ## 1.0.2 - April 22, 2013
75
-
76
- ### Bug fix
77
-
78
- - [#104][] Avoid conflict with ActiveSupport::Dependencies::Loadable. ([@nysalor][])
79
-
80
- ## 1.0.1 - April 22, 2013
81
-
82
- ### Bug fix
83
-
84
- - [#103][] Support old version of rubygems. (reported by [@ahoward][], fixed by [@thibaudgg][])
85
-
86
- ## 1.0.0 - April 20, 2013
87
-
88
- ### Bug fix
89
-
90
- - [#93][] Remove dependency operator in the "gem install" message. (reported by [@scottdavis][], fixed by [@rymai][])
91
-
92
- ### Changes & deprecations
93
-
94
- - [#98][] `Listen.to` does not block the current thread anymore. Use `Listen.to!` if you want the old behavior back. ([@rymai][])
95
- - [#98][] `Listen::Listener#start` does not block the current thread anymore. Use `Listen::Listener#start!` if you want the old behavior back. ([@rymai][])
96
- - [#98][] `Listen::Listener#start`'s `blocking` parameter is deprecated. ([@rymai][])
97
-
98
- ### Improvements
99
-
100
- - [#98][] New method: `Listen.to!` which blocks the current thread. ([@rymai][])
101
- - [#98][] New method: `Listen::Listener#start!` to start the listener and block the current thread. ([@martikaljuve][] & [@rymai][])
102
- - [#95][] Make `Listen::Listener` capable of listening to multiple directories, deprecates `Listen::MultiListener`, defaults `Listener#relative_paths` to `true` when listening to a single directory (see [#131][]). ([@rymai][])
103
- - [#85][] Compute the SHA1 sum only for regular files. ([@antifuchs][])
104
- - New methods: `Listen::Adapter#pause`, `Listen::Adapter#unpause` and `Listen::Adapter#paused?`. ([@rymai][])
105
- - Refactor `Listen::DirectoryRecord` internals. ([@rymai][])
106
- - Refactor `Listen::DependencyManager` internals. ([@rymai][])
107
-
108
- ## 0.7.3 - February 24, 2013
109
-
110
- ### Bug fixes
111
-
112
- - [#88][] Update wdm dependency. ([@mrbinky3000][])
113
- - [#78][] Depend on latest rb-inotify. ([@mbj][])
114
-
115
- ## 0.7.2 - January 11, 2013
116
-
117
- ### Bug fix
118
-
119
- - [#76][] Exception on filename which is not in UTF-8. ([@piotr-sokolowski][])
120
-
121
- ## 0.7.1 - January 6, 2013
122
-
123
- ### Bug fix
124
-
125
- - [#75][] Default high precision off if the mtime call fails. ([@zanker][])
126
-
127
- ## 0.7.0 - December 29, 2012
128
-
129
- ### Bug fix
130
-
131
- - [#73][] Rescue Errno::EOPNOTSUPP on sha1_checksum generation. ([@thibaudgg][])
132
-
133
- ### New feature
134
-
135
- - [#72][] Add support for *BSD with rb-kqueue. ([@mat813][])
136
-
137
- ## 0.6.0 - November 21, 2012
138
-
139
- ### New feature
140
-
141
- - [#68][] Add bang versions for `Listener#filter` and `Listener#ignore` methods. ([@tarsolya][])
142
-
143
- ## 0.5.3 - October 3, 2012
144
-
145
- ### Bug fixes
146
-
147
- - [#65][] Fix ruby warning in adapter.rb. ([@vongruenigen][])
148
- - [#64][] ENXIO raised when hashing UNIX domain socket file. ([@sunaku][])
149
-
150
- ## 0.5.2 - Septemper 23, 2012
151
-
152
- ### Bug fix
153
-
154
- - [#62][] Fix double change callback with polling adapter. ([@thibaudgg][])
155
-
156
- ## 0.5.1 - Septemper 18, 2012
157
-
158
- ### Bug fix
159
-
160
- - [#61][] Fix a synchronisation bug that caused constant fallback to polling. ([@Maher4Ever][])
161
-
162
- ## 0.5.0 - Septemper 1, 2012
163
-
164
- ### New features
165
-
166
- - Add a dependency manager to handle platform-specific gems. So there is no need anymore to install
167
- extra gems which will never be used on the user system. ([@Maher4Ever][])
168
- - Add a manual reporting mode to the adapters. ([@Maher4Ever][])
169
-
170
- ### Improvements
171
-
172
- - [#28][] Enhance the speed of detecting changes on Windows by using the [WDM][] library. ([@Maher4Ever][])
173
-
174
- ## 0.4.7 - June 27, 2012
175
-
176
- ### Bug fixes
177
-
178
- - Increase latency to 0.25, to avoid useless polling fallback. ([@thibaudgg][])
179
- - Change watched inotify events, to avoid duplication callback. ([@thibaudgg][])
180
- - [#41][] Use lstat instead of stat when calculating mtime. ([@ebroder][])
181
-
182
- ## 0.4.6 - June 20, 2012
183
-
184
- ### Bug fix
185
-
186
- - [#39][] Fix digest race condition. ([@dkubb][])
187
-
188
- ## 0.4.5 - June 13, 2012
189
-
190
- ### Bug fix
191
-
192
- - [#39][] Rescue Errno::ENOENT when path inserted doesn't exist. (reported by [@textgoeshere][], fixed by [@thibaudgg][] and [@rymai][])
193
-
194
- ## 0.4.4 - June 8, 2012
195
-
196
- ### Bug fixes
197
-
198
- - ~~[#39][] Non-existing path insertion bug. (reported by [@textgoeshere][], fixed by [@thibaudgg][])~~
199
- - Fix relative path for directories containing special characters. (reported by [@napcs][], fixed by [@netzpirat][])
200
-
201
- ## 0.4.3 - June 6, 2012
202
-
203
- ### Bug fixes
204
-
205
- - [#24][] Fail gracefully when the inotify limit is not enough for Listen to function. (reported by [@daemonza][], fixed by [@Maher4Ever][])
206
- - [#32][] Fix a crash when trying to calculate the checksum of unreadable files. (reported by [@nex3][], fixed by [@Maher4Ever][])
207
-
208
- ### Improvements
209
-
210
- - Add `Listener#relative_paths`. ([@Maher4Ever][])
211
- - Add `Adapter#started?`. ([@Maher4Ever][])
212
- - Dynamically detect the mtime precision used on a system. ([@Maher4Ever][] with help from [@nex3][])
213
-
214
- ## 0.4.2 - May 1, 2012
215
-
216
- ### Bug fixes
217
-
218
- - [#21][] Issues when listening to changes in relative paths. (reported by [@akerbos][], fixed by [@Maher4Ever][])
219
- - [#27][] Wrong reports for files modifications. (reported by [@cobychapple][], fixed by [@Maher4Ever][])
220
- - Fix segmentation fault when profiling on Windows. ([@Maher4Ever][])
221
- - Fix redundant watchers on Windows. ([@Maher4Ever][])
222
-
223
- ### Improvements
224
-
225
- - [#17][] Use regexp-patterns with the `ignore` method instead of supplying paths. (reported by [@fny][], added by [@Maher4Ever][])
226
- - Speed improvement when listening to changes in directories with ignored paths. ([@Maher4Ever][])
227
- - Added `.rbx` and `.svn` to ignored directories. ([@Maher4Ever][])
228
-
229
- ## 0.4.1 - April 15, 2012
230
-
231
- ### Bug fix
232
-
233
- - [#18][] Listener crashes when removing directories with nested paths. (reported by [@daemonza][], fixed by [@Maher4Ever][])
234
-
235
- ## 0.4.0 - April 9, 2012
236
-
237
- ### New features
238
-
239
- - Add `Adapter#wait_for_callback`. ([@Maher4Ever][])
240
- - Add `Listen::MultiListener` class to listen to multiple directories at once. ([@Maher4Ever][])
241
- - Allow passing multiple directories to the `Listen.to` method. ([@Maher4Ever][])
242
- - Add `blocking` option to `Listen#start` which can be used to disable blocking the current thread upon starting. ([@Maher4Ever][])
243
- - Use absolute-paths in callbacks by default instead of relative-paths. ([@Maher4Ever][])
244
- - Add `relative_paths` option to `Listen::Listener` to retain the old functionality. ([@Maher4Ever][])
245
-
246
- ### Improvements
247
-
248
- - Encapsulate thread spawning in the linux-adapter. ([@Maher4Ever][])
249
- - Encapsulate thread spawning in the darwin-adapter. ([@Maher4Ever][] with [@scottdavis][] help)
250
- - Encapsulate thread spawning in the windows-adapter. ([@Maher4Ever][])
251
- - Fix linux-adapter bug where Listen would report file-modification events on the parent-directory. ([@Maher4Ever][])
252
-
253
- ### Change
254
-
255
- - Remove `wait_until_listening` as adapters doesn't need to run inside threads anymore ([@Maher4Ever][])
256
-
257
- ## 0.3.3 - March 6, 2012
258
-
259
- ### Improvement
260
-
261
- - Improve pause/unpause. ([@thibaudgg][])
262
-
263
- ## 0.3.2 - March 4, 2012
264
-
265
- ### New feature
266
-
267
- - Add pause/unpause listener's methods. ([@thibaudgg][])
268
-
269
- ## 0.3.1 - February 22, 2012
270
-
271
- ### Bug fix
272
-
273
- - [#9][] Ignore doesn't seem to work. (reported by [@markiz][], fixed by [@thibaudgg][])
274
-
275
- ## 0.3.0 - February 21, 2012
276
-
277
- ### New features
278
-
279
- - Add automatic fallback to polling if system adapter doesn't work (like a DropBox folder). ([@thibaudgg][])
280
- - Add latency and force_polling options. ([@Maher4Ever][])
281
-
282
- ## 0.2.0 - February 13, 2012
283
-
284
- ### New features
285
-
286
- - Add checksum comparaison support for detecting consecutive file modifications made during the same second. ([@thibaudgg][])
287
- - Add rb-fchange support. ([@thibaudgg][])
288
- - Add rb-inotify support. ([@thibaudgg][] with [@Maher4Ever][] help)
289
- - Add rb-fsevent support. ([@thibaudgg][])
290
- - Add non-recursive diff with multiple directories support. ([@thibaudgg][])
291
- - Ignore `.DS_Store` files by default. ([@thibaudgg][])
292
-
293
- ## 0.1.0 - January 28, 2012
294
-
295
- - First version with only a polling adapter and basic features set (ignore & filter). ([@thibaudgg][])
296
-
297
- <!--- The following link definition list is generated by PimpMyChangelog --->
298
- [#9]: https://github.com/guard/listen/issues/9
299
- [#17]: https://github.com/guard/listen/issues/17
300
- [#18]: https://github.com/guard/listen/issues/18
301
- [#21]: https://github.com/guard/listen/issues/21
302
- [#24]: https://github.com/guard/listen/issues/24
303
- [#27]: https://github.com/guard/listen/issues/27
304
- [#28]: https://github.com/guard/listen/issues/28
305
- [#32]: https://github.com/guard/listen/issues/32
306
- [#39]: https://github.com/guard/listen/issues/39
307
- [#41]: https://github.com/guard/listen/issues/41
308
- [#61]: https://github.com/guard/listen/issues/61
309
- [#62]: https://github.com/guard/listen/issues/62
310
- [#64]: https://github.com/guard/listen/issues/64
311
- [#65]: https://github.com/guard/listen/issues/65
312
- [#68]: https://github.com/guard/listen/issues/68
313
- [#72]: https://github.com/guard/listen/issues/72
314
- [#73]: https://github.com/guard/listen/issues/73
315
- [#75]: https://github.com/guard/listen/issues/75
316
- [#76]: https://github.com/guard/listen/issues/76
317
- [#78]: https://github.com/guard/listen/issues/78
318
- [#85]: https://github.com/guard/listen/issues/85
319
- [#88]: https://github.com/guard/listen/issues/88
320
- [#93]: https://github.com/guard/listen/issues/93
321
- [#95]: https://github.com/guard/listen/issues/95
322
- [#96]: https://github.com/guard/listen/issues/96
323
- [#98]: https://github.com/guard/listen/issues/98
324
- [#103]: https://github.com/guard/listen/issues/103
325
- [#104]: https://github.com/guard/listen/issues/104
326
- [#110]: https://github.com/guard/listen/issues/110
327
- [#112]: https://github.com/guard/listen/issues/112
328
- [#113]: https://github.com/guard/listen/issues/113
329
- [#115]: https://github.com/guard/listen/issues/115
330
- [#117]: https://github.com/guard/listen/issues/117
331
- [#118]: https://github.com/guard/listen/issues/118
332
- [#120]: https://github.com/guard/listen/issues/120
333
- [#122]: https://github.com/guard/listen/issues/122
334
- [#124]: https://github.com/guard/listen/issues/124
335
- [#131]: https://github.com/guard/listen/issues/131
336
- [@21croissants]: https://github.com/21croissants
337
- [@Maher4Ever]: https://github.com/Maher4Ever
338
- [@ahoward]: https://github.com/ahoward
339
- [@akerbos]: https://github.com/akerbos
340
- [@antifuchs]: https://github.com/antifuchs
341
- [@chriseppstein]: https://github.com/chriseppstein
342
- [@cobychapple]: https://github.com/cobychapple
343
- [@daemonza]: https://github.com/daemonza
344
- [@dkubb]: https://github.com/dkubb
345
- [@ebroder]: https://github.com/ebroder
346
- [@fny]: https://github.com/fny
347
- [@luikore]: https://github.com/luikore
348
- [@markiz]: https://github.com/markiz
349
- [@martikaljuve]: https://github.com/martikaljuve
350
- [@mat813]: https://github.com/mat813
351
- [@mbj]: https://github.com/mbj
352
- [@mrbinky3000]: https://github.com/mrbinky3000
353
- [@napcs]: https://github.com/napcs
354
- [@netzpirat]: https://github.com/netzpirat
355
- [@nex3]: https://github.com/nex3
356
- [@nicobrevin]: https://github.com/nicobrevin
357
- [@nilbus]: https://github.com/nilbus
358
- [@nysalor]: https://github.com/nysalor
359
- [@piotr-sokolowski]: https://github.com/piotr-sokolowski
360
- [@rehevkor5]: https://github.com/rehevkor5
361
- [@rymai]: https://github.com/rymai
362
- [@scottdavis]: https://github.com/scottdavis
363
- [@sunaku]: https://github.com/sunaku
364
- [@tarsolya]: https://github.com/tarsolya
365
- [@textgoeshere]: https://github.com/textgoeshere
366
- [@thibaudgg]: https://github.com/thibaudgg
367
- [@vongruenigen]: https://github.com/vongruenigen
368
- [@zanker]: https://github.com/zanker
1
+ # Moved to [Github releases](https://github.com/guard/listen/releases) page.
data/README.md CHANGED
@@ -2,117 +2,64 @@
2
2
 
3
3
  The Listen gem listens to file modifications and notifies you about the changes.
4
4
 
5
+ ## WARNING
6
+
7
+ Master branch is `v2.0.0.beta` version, use the [v1.3 branch](https://github.com/guard/listen/tree/v1.3) for the stable release.
8
+
9
+ *BSD and Windows adapter are still a work in progress, any help is very welcome. Thanks!
10
+
5
11
  ## Features
6
12
 
7
- * Works everywhere!
8
13
  * Supports watching multiple directories from a single listener.
9
- * OS-specific adapters for Mac OS X 10.6+, Linux, *BSD and Windows.
10
- * Automatic fallback to polling if OS-specific adapter doesn't work.
14
+ * OS-specific adapters on MRI for Mac OS X 10.6+, Linux, *BSD and Windows, [more info](#listen-adapters) bellow.
11
15
  * Detects file modification, addition and removal.
12
- * File content checksum comparison for modifications made under the same second.
13
- * Allows supplying regexp-patterns to ignore and filter paths for better results.
14
- * Tested on all Ruby environments via [Travis CI](https://travis-ci.org/guard/listen).
16
+ * Allows supplying regexp-patterns to ignore paths for better results.
17
+ * File content checksum comparison for modifications made under the same second (OS X only).
18
+ * Tested on MRI Ruby environments (1.9+ only) via [Travis CI](https://travis-ci.org/guard/listen), JRuby and Rubinius should work with polling.
15
19
 
16
- ## Pending features
20
+ Please note that Windows and *BSD adapter aren't continuously and automaticaly tested.
17
21
 
18
- Still not implemented, pull requests are welcome.
22
+ ## Pending features
19
23
 
20
- * Symlinks support. [#25](https://github.com/guard/listen/issues/25)
21
- * Signal handling. [#105](https://github.com/guard/listen/issues/105)
22
24
  * Non-recursive directory scanning. [#111](https://github.com/guard/listen/issues/111)
25
+ * Symlinks support. [#25](https://github.com/guard/listen/issues/25)
23
26
 
24
- ## Install
25
-
26
- ### Using Bundler
27
-
28
- The simplest way to install Listen is to use Bundler.
29
-
30
- Add Listen to your Gemfile:
31
-
32
- ```ruby
33
- group :development do
34
- gem 'listen'
35
- end
36
- ```
37
-
38
- and install it by running Bundler:
27
+ Pull request or help is very welcome for these.
39
28
 
40
- ```bash
41
- $ bundle
42
- ```
29
+ ## Changelog
43
30
 
44
- ### Install the gem with RubyGems
31
+ The Changelog is on now on the [Github releases](https://github.com/guard/listen/releases) section.
45
32
 
46
- ```bash
47
- $ gem install listen
48
- ```
33
+ ## Install
49
34
 
50
- ### On Windows
51
-
52
- If your are on Windows and using Ruby MRI >= 1.9.2 you can try to use the [`wdm`](https://github.com/Maher4Ever/wdm) instead of polling.
53
- Please add the following to your Gemfile:
35
+ The simplest way to install Listen is to use [Bundler](http://bundler.io).
54
36
 
55
37
  ```ruby
56
- require 'rbconfig'
57
- gem 'wdm', '>= 0.1.0' if RbConfig::CONFIG['target_os'] =~ /mswin|mingw/i
38
+ gem 'listen', '~> 2.0'
58
39
  ```
59
40
 
60
41
  ## Usage
61
42
 
62
- There are **two ways** to use Listen:
63
-
64
- 1. Block API: Call `Listen.to`/`Listen.to!` with either a single directory or multiple directories, then define the `change` callback in a block.
65
- 2. "Object" API: Create a `listener` object and use it in a chainable way.
66
-
67
- ### Block API
43
+ Call `Listen.to` with either a single directory or multiple directories, then define the "changes" callback in a block.
68
44
 
69
45
  ``` ruby
70
- # Listen to a single directory.
71
- Listen.to('dir/path/to/listen', :filter => /\.rb$/, :ignore => %r{ignored/path/}) do |modified, added, removed|
72
- # ...
73
- end
74
-
75
- # Listen to multiple directories.
76
- Listen.to('dir/to/awesome_app', 'dir/to/other_app', :filter => /\.rb$/, :latency => 0.1) do |modified, added, removed|
77
- # ...
46
+ listener = Listen.to('dir/to/listen', 'dir/to/listen2') do |modified, added, removed|
47
+ puts "modified absolute path: #{modified}"
48
+ puts "added absolute path: #{added}"
49
+ puts "removed absolute path: #{removed}"
78
50
  end
51
+ listener.start # not blocking
52
+ sleep
79
53
  ```
80
54
 
81
- ### "Object" API
82
-
83
- ``` ruby
84
- listener = Listen.to('dir/path/to/listen')
85
- listener = listener.ignore(%r{^ignored/path/})
86
- listener = listener.filter(/\.rb$/)
87
- listener = listener.latency(0.5)
88
- listener = listener.force_polling(true)
89
- listener = listener.polling_fallback_message(false)
90
- listener = listener.force_adapter(Listen::Adapters::Linux)
91
- listener = listener.change(&callback)
92
- listener.start
93
- ```
94
-
95
- **Note**: All the "Object" API methods except `start`/`start!` return the listener
96
- and are thus chainable:
97
-
98
- ``` ruby
99
- Listen.to('dir/path/to/listen')
100
- .ignore(%r{^ignored/path/})
101
- .filter(/\.rb$/)
102
- .latency(0.5)
103
- .force_polling(true)
104
- .polling_fallback_message('custom message')
105
- .change(&callback)
106
- .start
107
- ```
108
-
109
- ### Pause/Unpause
55
+ ### Pause / unpause / stop
110
56
 
111
- Listener can also easily be paused/unpaused:
57
+ Listener can also be easily paused/unpaused:
112
58
 
113
59
  ``` ruby
114
- listener = Listen.to('dir/path/to/listen')
115
- listener.start # non-blocking mode
60
+ listener = Listen.to('dir/path/to/listen') { |modified, added, removed| # ... }
61
+ listener.start
62
+ listener.listen? # => true
116
63
  listener.pause # stop listening to changes
117
64
  listener.paused? # => true
118
65
  listener.unpause # start listening to changes again
@@ -123,178 +70,98 @@ listener.stop # stop completely the listener
123
70
 
124
71
  Changes to the listened-to directories gets reported back to the user in a callback.
125
72
  The registered callback gets invoked, when there are changes, with **three** parameters:
126
- `modified_paths`, `added_paths` and `removed_paths` in that particular order.
73
+ `modified`, `added` and `removed` paths, in that particular order.
74
+ Paths are always returned in their absolute form.
127
75
 
128
- You can register a callback in two ways. The first way is by passing a block when calling
129
- the `Listen.to`/`Listen.to!` method or when initializing a listener object:
76
+ Example:
130
77
 
131
78
  ```ruby
132
- Listen.to('path/to/app') do |modified, added, removed|
79
+ listener = Listen.to('path/to/app') do |modified, added, removed|
133
80
  # This block will be called when there are changes.
134
81
  end
135
-
136
- # or ...
137
-
138
- listener = Listen::Listener.new('path/to/app') do |modified, added, removed|
139
- # This block will be called when there are changes.
140
- end
141
-
82
+ listener.start
83
+ sleep
142
84
  ```
143
85
 
144
- The second way to register a callback is by calling the `#change` method on a
145
- listener passing it a block:
86
+ or ...
146
87
 
147
88
  ```ruby
148
89
  # Create a callback
149
90
  callback = Proc.new do |modified, added, removed|
150
91
  # This proc will be called when there are changes.
151
92
  end
152
-
153
- listener = Listen.to('dir')
154
- listener.change(&callback) # convert the callback to a block and register it
155
-
93
+ listener = Listen.to('dir', &callback)
156
94
  listener.start
157
- ```
158
-
159
- ### Paths in callbacks
160
-
161
- Listeners invoke callbacks passing them absolute paths by default:
162
-
163
- ```ruby
164
- # Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
165
- # the listener.
166
- Listen.to('/home/user/app/css') do |modified, added, removed|
167
- modified.inspect # => ['/home/user/app/css/style.css']
168
- end
169
- ```
170
-
171
- #### Relative paths in callbacks
172
-
173
- When creating a listener for a **single** path (more specifically a `Listen::Listener` instance),
174
- you can pass `:relative_paths => true` as an option to get relative paths in
175
- your callback:
176
-
177
- ```ruby
178
- # Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
179
- # the listener.
180
- Listen.to('/home/user/app/css', :relative_paths => true) do |modified, added, removed|
181
- modified.inspect # => ['style.css']
182
- end
183
- ```
184
-
185
- Passing the `:relative_paths => true` option won't work when listening to multiple
186
- directories:
187
-
188
- ```ruby
189
- # Assume someone changes the 'style.css' file in '/home/user/app/css' after creating
190
- # the listener.
191
- Listen.to('/home/user/app/css', '/home/user/app/js', :relative_paths => true) do |modified, added, removed|
192
- modified.inspect # => ['/home/user/app/css/style.css']
193
- end
95
+ sleep
194
96
  ```
195
97
 
196
98
  ## Options
197
99
 
198
- All the following options can be set through the `Listen.to`/`Listen.to!` params
199
- or via ["Object" API](#object-api) methods:
100
+ All the following options can be set through the `Listen.to` after the directory path(s) params.
200
101
 
201
102
  ```ruby
202
- :ignore => %r{app/CMake/}, /\.pid$/ # Ignore a list of paths (root directory or sub-dir)
203
- # default: See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::DirectoryRecord
103
+ ignore: [%r{/foo/bar}, /\.pid$/, /\.coffee$/] # Ignore a list of paths
104
+ # default: See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer
204
105
 
205
- :filter => /\.rb$/, /\.coffee$/ # Filter files to listen to via a regexps list.
206
- # default: none
106
+ ignore!: %r{/foo/bar} # Same as ignore options, but overwrite default ignored paths.
207
107
 
208
- :latency => 0.5 # Set the delay (**in seconds**) between checking for changes
209
- # default: 0.25 sec (1.0 sec for polling)
108
+ latency: 0.5 # Set the delay (**in seconds**) between checking for changes
109
+ # default: 0.25 sec (1.0 sec for polling)
210
110
 
211
- :force_adapter => Listen::Adapters::Linux # Force the use of a particular adapter class
212
- # default: none
111
+ force_polling: true # Force the use of the polling adapter
112
+ # default: none
213
113
 
214
- :force_polling => true # Force the use of the polling adapter
215
- # default: none
114
+ polling_fallback_message: 'custom message' # Set a custom polling fallback message (or disable it with false)
115
+ # default: "Listen will be polling for changes. Learn more at https://github.com/guard/listen#polling-fallback."
216
116
 
217
- :polling_fallback_message => 'custom message' # Set a custom polling fallback message (or disable it with false)
218
- # default: "Listen will be polling for changes. Learn more at https://github.com/guard/listen#polling-fallback."
219
-
220
- :relative_paths => true # Enable the use of relative paths in the callback.
221
- # default: false
117
+ debug: true # Enable Celluloid logger
118
+ # default: false
222
119
  ```
223
120
 
224
- ### Note on the patterns for ignoring and filtering paths
225
-
226
- Just like the unix convention of beginning absolute paths with the
227
- directory-separator (forward slash `/` in unix) and with no prefix for relative paths,
228
- Listen doesn't prefix relative paths (to the watched directory) with a directory-separator.
229
-
230
- Therefore make sure _NOT_ to prefix your regexp-patterns for filtering or ignoring paths
231
- with a directory-separator, otherwise they won't work as expected.
121
+ ## Listen adapters
232
122
 
233
- As an example: to ignore the `build` directory in a C-project, use `%r{build/}`
234
- and not `%r{/build/}`.
123
+ The Listen gem has a set of adapters to notify it when there are changes.
124
+ There are 4 OS-specific adapters to support Darwin, Linux, *BSD and Windows.
125
+ These adapters are fast as they use some system-calls to implement the notifying function.
235
126
 
236
- Use `#filter!` and `#ignore!` methods to overwrites default patterns.
127
+ There is also a polling adapter which is a cross-platform adapter and it will
128
+ work on any system. This adapter is slower than the rest of the adapters.
237
129
 
238
- ## Blocking listening to changes
130
+ Darwin and Linux adapter are dependencies of the Listen gem so they work out of the box. For other adapters a specific gem need to be added to your Gemfile, please read bellow.
239
131
 
240
- Calling `Listen.to` with a block doesn't block the current thread. If you want
241
- to block the current thread instead until the listener is stopped (which needs
242
- to be done from another thread), you can use `Listen.to!`.
132
+ The Listen gem choose the good adapter (if present) automatically. If you
133
+ want to force the use of the polling adapter use the `:force_polling` option
134
+ while initializing the listener.
243
135
 
244
- Similarly, if you're using the "Object" API, you can use `#start!` instead of `#start` to block the
245
- current thread until the listener is stopped.
136
+ ### On Windows
246
137
 
247
- Here is an example of using a listener in the blocking mode:
138
+ If your are on Windows you can try to use the [`wdm`](https://github.com/Maher4Ever/wdm) instead of polling.
139
+ Please add the following to your Gemfile:
248
140
 
249
141
  ```ruby
250
- Listen.to!('dir/path/to/listen') # block execution
251
-
252
- # Code here will not run until the listener is stopped
253
-
142
+ require 'rbconfig'
143
+ gem 'wdm', '>= 0.1.0' if RbConfig::CONFIG['target_os'] =~ /mswin|mingw|cygwin/i
254
144
  ```
255
145
 
256
- Here is an example of using a listener started with the "Object" API in blocking mode:
257
-
258
- ```ruby
259
- listener = Listen.to('dir/path/to/listen')
260
- listener.start! # block execution
146
+ ### On *BSD
261
147
 
262
- # Code here will not run until the listener is stopped
148
+ If your are on *BSD you can try to use the [`rb-kqueue`](https://github.com/mat813/rb-kqueue) instead of polling.
149
+ Please add the following to your Gemfile:
263
150
 
151
+ ```ruby
152
+ require 'rbconfig'
153
+ gem 'rb-kqueue', '>= 0.2' if RbConfig::CONFIG['target_os'] =~ /freebsd/i
264
154
  ```
265
155
 
266
- **Note**: Using the `Listen.to!` helper-method with or without a callback-block
267
- will always start the listener right away and block execution of the current thread.
268
-
269
- ## Listen adapters
270
-
271
- The Listen gem has a set of adapters to notify it when there are changes.
272
- There are 4 OS-specific adapters to support Mac, Linux, *BSD and Windows.
273
- These adapters are fast as they use some system-calls to implement the notifying function.
274
-
275
- There is also a polling adapter which is a cross-platform adapter and it will
276
- work on any system. This adapter is unfortunately slower than the rest of the adapters.
277
-
278
- The Listen gem will choose the best and working adapter for your machine automatically. If you
279
- want to force the use of the polling adapter, either use the `:force_polling` option
280
- while initializing the listener or call the `#force_polling` method on your listener
281
- before starting it.
282
-
283
- It is also possible to force the use of a particular adapter, by using the `:force_adapter`
284
- option. This option skips the usual adapter choosing mechanism and uses the given
285
- adapter class instead. The adapter choosing mechanism requires write permission
286
- to your watched directories and will needlessly load code, which isn't always desirable.
287
-
288
- ## Polling fallback
156
+ ### Issues
289
157
 
290
- When a OS-specific adapter doesn't work the Listen gem automatically falls back to the polling adapter.
291
- Here are some things you could try to avoid the polling fallback:
158
+ Sometimes OS-specific adapter doesn't work, :'(
159
+ Here are some things you could try to avoid forcing polling.
292
160
 
293
161
  * [Update your Dropbox client](http://www.dropbox.com/downloading) (if used).
294
- * Increase latency. (Please [open an issue](https://github.com/guard/listen/issues/new)
295
- if you think that default is too low.)
296
162
  * Move or rename the listened folder.
297
163
  * Update/reboot your OS.
164
+ * Increase latency.
298
165
 
299
166
  If your application keeps using the polling-adapter and you can't figure out why, feel free to [open an issue](https://github.com/guard/listen/issues/new) (and be sure to [give all the details](https://github.com/guard/listen/blob/master/CONTRIBUTING.md)).
300
167
 
@@ -321,19 +188,18 @@ For questions please join us in our [Google group](http://groups.google.com/grou
321
188
  * [Travis Tilley (ttilley)][] for this awesome work on [fssm][] & [rb-fsevent][].
322
189
  * [Nathan Weizenbaum (nex3)][] for [rb-inotify][], a thorough inotify wrapper.
323
190
  * [Mathieu Arnold (mat813)][] for [rb-kqueue][], a simple kqueue wrapper.
324
- * [stereobooster][] for [rb-fchange][], windows support wouldn't exist without him.
191
+ * [Maher Sallam][] for [wdm][], windows support wouldn't exist without him.
325
192
  * [Yehuda Katz (wycats)][] for [vigilo][], that has been a great source of inspiration.
326
193
 
327
- ## Authors
194
+ ## Author
328
195
 
329
- * [Thibaud Guillaume-Gentil][] ([@thibaudgg](http://twitter.com/thibaudgg))
330
- * [Maher Sallam][] ([@mahersalam](http://twitter.com/mahersalam))
196
+ * [Thibaud Guillaume-Gentil (thibaudgg)][] ([@thibaudgg](http://twitter.com/thibaudgg))
331
197
 
332
198
  ## Contributors
333
199
 
334
200
  [https://github.com/guard/listen/contributors](https://github.com/guard/listen/contributors)
335
201
 
336
- [Thibaud Guillaume-Gentil]: https://github.com/thibaudgg
202
+ [Thibaud Guillaume-Gentil (thibaudgg)]: https://github.com/thibaudgg
337
203
  [Maher Sallam]: https://github.com/Maher4Ever
338
204
  [Michael Kessler (netzpirat)]: https://github.com/netzpirat
339
205
  [Travis Tilley (ttilley)]: https://github.com/ttilley
@@ -347,3 +213,4 @@ For questions please join us in our [Google group](http://groups.google.com/grou
347
213
  [rb-kqueue]: https://github.com/mat813/rb-kqueue
348
214
  [Yehuda Katz (wycats)]: https://github.com/wycats
349
215
  [vigilo]: https://github.com/wycats/vigilo
216
+ [wdm]: https://github.com/Maher4Ever/wdm