The Listen gem listens to file modifications and notifies you about the changes.
- Works everywhere!
- Supports watching multiple directories from a single listener.
- 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.
- Allows ignoring paths and supplying filters for better results.
- Tested on all Ruby environments via travis-ci.
gem install listen
There are two ways to use Listen:
Listen.towith either a single directory or multiple directories, then define the
changecallback in a block.
- Create a
listenerobject and use it in an (ARel style) chainable way.
Feel free to give your feeback via Listen issues
# Listen to a single directory. Listen.to('dir/path/to/listen', filter: /.*\.rb/, ignore: '/ignored/path') do |modified, added, removed| # ... end # Listen to multiple directories. Listen.to('dir/to/awesome_app', 'dir/to/other_app', filter: /.*\.rb/, latency: 0.1) do |modified, added, removed| # ... end
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.polling_fallback_message(false) listener = listener.change(&callback) listener.start # blocks execution!
Listen.to('dir/path/to/listen') .ignore('/ignored/path') .filter(/.*\.rb/) .latency(0.5) .force_polling(true) .polling_fallback_message('custom message') .change(&callback) .start # blocks execution!
Listener can also easily be paused/unpaused:
listener = Listen.to('dir/path/to/listen') listener.start(false) # non-blocking mode listener.pause # stop listening to changes listener.paused? # => true listener.unpause listener.stop
Listening to changes on multiple directories
The Listen gem provides the
MultiListener class to watch multiple directories and
handle their changes from a single listener:
listener = Listen::MultiListener.new('app/css', 'app/js') listener.latency(0.5) # Configure the listener to your needs... listener.start # blocks execution!
For an easier access, the
Listen.to method can also be used to create a multi-listener:
listener = Listen.to('app/css', 'app/js') .ignore('vendor') # both js/vendor and css/vendor will be ignored .change(&assets_callback) listener.start # blocks execution!
Changes to the listened-to directories gets reported back to the user in a callback.
The registered callback gets invoked, when there are changes, with three parameters:
removed_paths in that particular order.
You can register a callback in two ways. The first way is by passing a block when calling
Listen.to method or when initializing a listener object:
Listen.to('path/to/app') do |modified, added, removed| # This block will be called when there are changes. end # or ... listener = Listen::Listener.new('path/to/app') do |modified, added, removed| # This block will be called when there are changes. end
The second way to register a callback is be calling the
change method on any
listener passing it a block:
# Create a callback callback = Proc.new do |modified, added, removed| # This proc will be called when there are changes. end listener = Listen.to('dir') listener.change(&callback) # convert the callback to a block and register it listener.start # blocks execution
Paths in callbacks
Listeners invoke callbacks passing them absolute paths by default:
# Assume someone changes the 'style.css' file in '/home/user/app/css' after creating # the listener. Listen.to('/home/user/app/css') do |modified, added, removed| modified.inspect # => ['/home/user/app/css/style.css'] end
Relative paths in callbacks
When creating a listener for a single path (more specifically a
you can pass
:relative_paths => true as an option to get relative paths in
# Assume someone changes the 'style.css' file in '/home/user/app/css' after creating # the listener. Listen.to('/home/user/app/css', :relative_paths => true) do |modified, added, removed| modified.inspect # => ['style.css'] end
:relative_paths => true option won't work when listeneing to multiple
# Assume someone changes the 'style.css' file in '/home/user/app/css' after creating # the listener. Listen.to('/home/user/app/css', '/home/user/app/js', :relative_paths => true) do |modified, added, removed| modified.inspect # => ['/home/user/app/css/style.css'] end
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."
Non-blocking listening to changes
Starting a listener blocks the current thread by default. That means any code after the
start call won't be run until the listener is stopped (which needs to be done from another thread).
For advanced usage there is an option to disable this behavior and have the listener start working
in the background without blocking. To enable non-blocking listening the
start method of
the listener (be it
MultiListener) needs to be called with
false as a parameter.
Here is an example of using a listener in the non-blocking mode:
listener = Listen.to('dir/path/to/listen') listener.start(false) # doesn't block execution # Code here will run immediately after starting the listener
note: Using the
Listen.to helper-method with a callback-block will always
block execution. See the "Block API" section for an example.
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
while initializing the listener or call the
force_polling method on your listener
before starting it.
When a OS-specific adapter doesn't work the Listen gem automatically falls back to the polling adapter. Here are some things you could try to avoid the polling fallback:
- Update your Dropbox client (if used).
- Increase latency. (Please open an issue if you think that default is too low.)
- Move or rename the listened folder.
- Update/reboot your OS.
If your application keeps using the polling-adapter and you can't figure out why, feel free to open an issue (and be sure to give all the details).
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:portabilitymust 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
- 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.