Listen Build Status

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.

  1. call Listen.to with a path params, and define callbacks in a block.
  2. 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.polling_fallback_message(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)
      .polling_fallback_message('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."

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:

If it still falling back, feel free to open an issue (and be sure to give all details).

Development Dependency Status

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

Author

Thibaud Guillaume-Gentil (@thibaudgg)

Contributors

https://github.com/guard/listen/contributors