Listen
The Listen gem listens to file modifications and notifies you about the changes.
Features
- Works everywhere!
- OS-specific adapters for Mac OS X 10.6+, Linux and Windows.
- Automatic fallback to polling if OS-specific adapter doesn't work.
- Detects files modification, addidation and removal.
- Checksum comparaison for modifications made under the same second.
- Tested on all Ruby environments via travis-ci.
- Threadable.
Install
gem install listen
Usage
There are two ways you can use Listen.
- call
Listen.to
with a path params, and define callbacks in a block. - create a
listener
object usable in an (ARel style) chainable way.
Feel free to give your feeback via Listen issues
Block API
Listen.to('dir/path/to/listen', filter: /.*\.rb/, ignore: '/ignored/path') do |modified, added, removed|
# ...
end
"Object" API
listener = Listen.to('dir/path/to/listen')
listener = listener.ignore('/ignored/path')
listener = listener.filter(/.*\.rb/)
listener = listener.latency(0.5)
listener = listener.force_polling(true)
listener = listener.(false)
listener = listener.change(&callback)
listener.start # enter the run loop
listener.stop
Chainable
Listen.to('dir/path/to/listen')
.ignore('/ignored/path')
.filter(/.*\.rb/)
.latency(0.5)
.force_polling(true)
.('custom message')
.change(&callback)
.start # enter the run loop
Multiple listeners support available via Thread
listener = Listen.to(dir1).ignore('/ignored/path/')
styles = listener.filter(/.*\.css/).change(&style_callback)
scripts = listener.filter(/.*\.js/).change(&scripts_callback)
Thread.new { styles.start } # enter the run loop
Thread.new { scripts.start } # enter the run loop
Options
These options can be set through Listen.to
params or via methods (see the "Object" API)
:filter => /.*\.rb/, /.*\.coffee/ # Filter files to listen to via a regexps list.
# default: none
:ignore => 'path1', 'path2' # Ignore a list of paths (root directory or sub-dir)
# default: '.bundle', '.git', '.DS_Store', 'log', 'tmp', 'vendor'
:latency => 0.5 # Set the delay (**in seconds**) between checking for changes
# default: 0.1 sec (1.0 sec for polling)
:force_polling => true # Force the use of the polling adapter
# default: none
:polling_fallback_message => 'custom message' # Set a custom polling fallback message (or disable it with `false`)
# default: "WARNING: Listen fallen back to polling, learn more at https://github.com/guard/listen#fallback."
Pause/Unpause
Listener can also easily be paused/unpaused:
listener = Listen.to('dir/path/to/listen')
listener.start # enter the run loop
listener.pause # stop the run loop and enter the wait loop
listener.unpause # re-enter the run loop
listener.stop
Listen adapters
The Listen gem has a set of adapters to notify it when there are changes. There are 3 OS-specific adapters to support Mac, Linux and Windows. These adapters are fast as they use some system-calls to implement the notifying function.
There is also a polling adapter which is a cross-platform adapter and it will work on any system. This adapter is unfortunately slower than the rest of the adapters.
The Listen gem will choose the best and working adapter for your machine automatically. If you
want to force the use of the polling adapter, either use the :force_polling
option
while initializing the listener or call the force_polling
method on your listener
before starting it.
Polling fallback
When the OS-specific adapter doesn't work the Listen gem automatically falls back to the polling adapter. Here some things to try to avoiding this fallback:
- Update your Dropbox client (if used).
- Move or rename the listened folder.
- Update/reboot your OS.
If it still falling back, feel free to open an issue (and be sure to give all details).
Development
Pull requests are very welcome! Please try to follow these simple rules if applicable:
- Please create a topic branch for every separate change you make.
- Make sure your patches are well tested. All specs run with
rake spec:portability
must pass. - Update the Yard documentation.
- Update the README.
- Update the CHANGELOG for noteworthy changes.
- Please do not change the version number.
For questions please join us in our Google group or on
#guard
(irc.freenode.net).
Acknowledgment
- Michael Kessler (netzpirat) for having written the initial specs.
- Travis Tilley (ttilley) for this awesome work on fssm & rb-fsevent.
- Nathan Weizenbaum (nex3) for rb-inotify, a thorough inotify wrapper.
- stereobooster for rb-fchange, windows support wouldn't exist without him.
- Yehuda Katz (wycats) for vigilo, that has been a great source of inspiration.
Author
Thibaud Guillaume-Gentil (@thibaudgg)