![](\"http:\/\/badge.fury.io\/rb\/listen.png\"){kind=icon}
![](\"http:\/\/travis-ci.org\/guard\/listen.png\")
![](\"http:\/\/gemnasium.com\/guard\/listen.png\")
![](\"http:\/\/codeclimate.com\/github\/guard\/listen.png\")
![](\"http:\/\/coveralls.io\/repos\/guard\/listen\/badge.png?branch=master\"){kind=icon}
<\/p>\n <\/p>\n
The Listen gem listens to file modifications and notifies you about the changes.<\/p>\n
Just head over here: https:\/\/github.com\/guard\/listen\/wiki\/Quickfixes,-known-issues-and-workarounds<\/p>\n
Make sure you know these few basic tricks: https:\/\/github.com\/guard\/listen\/wiki\/Tips-and-Techniques<\/p>\n
Please note that:<\/p>\n
Pull request or help is very welcome for these.<\/p>\n
The simplest way to install Listen is to use Bundler.<\/p>\n
gem 'listen', '~> 2.7' # this prevents upgrading to 3.x\n<\/code><\/pre>\nUsage<\/h2>\n
Call Listen.to<\/code> with either a single directory or multiple directories, then define the \u201cchanges\u201d callback in a block.<\/p>\nlistener = Listen.to('dir\/to\/listen', 'dir\/to\/listen2') do |modified, added, removed|\n puts \"modified absolute path: #{modified}\"\n puts \"added absolute path: #{added}\"\n puts \"removed absolute path: #{removed}\"\nend\nlistener.start # not blocking\nsleep\n<\/code><\/pre>\nPause \/ unpause \/ stop<\/h3>\n
Listeners can also be easily paused\/unpaused:<\/p>\n
listener = Listen.to('dir\/path\/to\/listen') { |modified, added, removed| # ... }\n\nlistener.start\nlistener.paused? # => false\nlistener.processing? # => true\n\nlistener.pause # stops processing changes (but keeps on collecting them)\nlistener.paused? # => true\nlistener.processing? # => false\n\nlistener.unpause # resumes processing changes (\"start\" would do the same)\nlistener.stop # stop both listening to changes and processing them\n<\/code><\/pre>\nNote: While paused, Listen keeps on collecting changes in the background – to clear them, call \u201cstop\u201d<\/p>\n
Note: You should keep track of all started listeners and stop them properly on finish.<\/p>\n
Ignore \/ ignore!<\/h3>\n
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<\/code> option\/method or overwrite default with ignore!<\/code> option\/method.<\/p>\nlistener = Listen.to('dir\/path\/to\/listen', ignore: \/\\.txt\/) { |modified, added, removed| # ... }\nlistener.start\nlistener.ignore! \/\\.pkg\/ # overwrite all patterns and only ignore pkg extension.\nlistener.ignore \/\\.rb\/ # ignore rb extension in addition of pkg.\nsleep\n<\/code><\/pre>\nNote: Ignoring regexp patterns are evaluated against relative paths.<\/p>\n
Note: ignoring paths does not improve performance – except when Polling<\/p>\n
Only<\/h3>\n
Listen catches all files (less the ignored once) by default, if you want to only listen to a specific type of file (ie: just rb extension) you should use the only<\/code> option\/method.<\/p>\nlistener = Listen.to('dir\/path\/to\/listen', only: \/\\.rb$\/) { |modified, added, removed| # ... }\nlistener.start\nlistener.only \/_spec\\.rb$\/ # overwrite all existing only patterns.\nsleep\n<\/code><\/pre>\nNote: \u2018:only\u2019 regexp patterns are evaluated only against relative file<\/strong> paths.<\/p>\nChanges callback<\/h2>\n
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<\/strong> parameters: modified<\/code>, added<\/code> and removed<\/code> paths, in that particular order. Paths are always returned in their absolute form.<\/p>\nExample:<\/p>\n
listener = Listen.to('path\/to\/app') do |modified, added, removed|\n # This block will be called when there are changes.\nend\nlistener.start\nsleep\n<\/code><\/pre>\nor \u2026<\/p>\n
# Create a callback\ncallback = Proc.new do |modified, added, removed|\n # This proc will be called when there are changes.\nend\nlistener = Listen.to('dir', &callback)\nlistener.start\nsleep\n<\/code><\/pre>\nOptions<\/h2>\n
All the following options can be set through the Listen.to<\/code> after the directory path(s) params.<\/p>\nignore: [%r{\/foo\/bar}, \/\\.pid$\/, \/\\.coffee$\/] # Ignore a list of paths\n # default: See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer\n\nignore!: %r{\/foo\/bar} # Same as ignore options, but overwrite default ignored paths.\n\nonly: %r{.rb$} # Only listen to specific files\n # default: none\n\nlatency: 0.5 # Set the delay (**in seconds**) between checking for changes\n # default: 0.25 sec (1.0 sec for polling)\n\nwait_for_delay: 4 # Set the delay (**in seconds**) between calls to the callback when changes exist\n # default: 0.10 sec\n\nforce_polling: true # Force the use of the polling adapter\n # default: none\n\nrelative: false # Whether changes should be relative to current dir or not\n # default: false\n\ndebug: true # Enable Celluloid logger\n # default: false\n\npolling_fallback_message: 'custom message' # Set a custom polling fallback message (or disable it with false)\n # default: \"Listen will be polling for changes. Learn more at https:\/\/github.com\/guard\/listen#listen-adapters.\"\n<\/code><\/pre>\nAlso, setting the environment variable LISTEN_GEM_DEBUGGING=1<\/code> does the same as debug: true<\/code> above.<\/p>\nListen adapters<\/h2>\n
The Listen gem has a set of adapters to notify it when there are changes.<\/p>\n
There are 4 OS-specific adapters to support Darwin, Linux, *BSD and Windows. These adapters are fast as they use some system-calls to implement the notifying function.<\/p>\n
There is also a polling adapter – although it\u2019s much slower than other adapters, it works on every platform\/system and scenario (including network filesystems such as VM shared folders).<\/p>\n
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.<\/p>\n
The Listen gem will choose the best adapter automatically, if present. If you want to force the use of the polling adapter, use the :force_polling<\/code> option while initializing the listener.<\/p>\nOn Windows<\/h3>\n
If your are on Windows, it\u2019s recommended to use the wdm<\/code> adapter instead of polling.<\/p>\nPlease add the following to your Gemfile:<\/p>\n
gem 'wdm', '>= 0.1.0' if Gem.win_platform?\n<\/code><\/pre>\nOn *BSD<\/h3>\n
If your are on *BSD you can try to use the rb-kqueue<\/code> adapter instead of polling.<\/p>\nPlease add the following to your Gemfile:<\/p>\n
require 'rbconfig'\nif RbConfig::CONFIG['target_os'] =~ \/bsd|dragonfly\/i\n gem 'rb-kqueue', '>= 0.2'\nend\n\n<\/code><\/pre>\nGetting the polling fallback message?<\/h3>\n
Please visit the installation section of the Listen WIKI for more information and options for potential fixes.<\/p>\n
Issues and troubleshooting<\/h3>\n
NOTE: without providing the output after setting the LISTEN_GEM_DEBUGGING=1<\/code> environment variable, it can be almost impossible to guess why listen is not working as expected.<\/em><\/p>\nSee TROUBLESHOOTING<\/p>\n
Performance<\/h2>\n
If Listen seems slow or unresponsive, make sure you\u2019re not using the Polling adapter (you should see a warning upon startup if you are).<\/p>\n
Also, if the directories you\u2019re watching contain many files, make sure you\u2019re:<\/p>\n
\n- not using Polling (ideally)<\/li>\n
- using
:ignore<\/code> and :only<\/code> options to avoid tracking directories you don\u2019t care about (important with Polling and on MacOS)<\/li>\n- running Listen with the
:latency<\/code> and :wait_for_delay<\/code> options not too small or too big (depends on needs)<\/li>\n- not watching directories with log files, database files or other frequently changing files<\/li>\n
- not using a version of Listen prior to 2.7.7<\/li>\n
- not getting silent crashes within Listen (see LISTEN_GEM_DEBUGGING=2)<\/li>\n
- not running multiple instances of Listen in the background<\/li>\n
- using a file system with atime modification disabled (ideally)<\/li>\n
- not using a filesystem with inaccurate file modification times (ideally), e.g. HFS, VFAT<\/li>\n
- not buffering to a slow terminal (e.g. transparency + fancy font + slow gfx card + lots of output)<\/li>\n
- ideally not running a slow encryption stack, e.g. btrfs + ecryptfs<\/li>\n<\/ul>\n
When in doubt, LISTEN_GEM_DEBUGGING=2 can help discover the actual events and time they happened.<\/p>\n
Forwarding file events over TCP<\/h2>\n
Listen is capable of forwarding file events over the network using a messaging protocol. This can be useful for virtualized development environments when file events are unavailable, as is the case with shared folders in VMs.<\/p>\n
Vagrant uses Listen in it\u2019s rsync-auto mode to solve this issue.<\/p>\n
To broadcast events over TCP programmatically, use the forward_to<\/code> option with an address – just a port or a hostname\/port combination:<\/p>\nlistener = Listen.to 'path\/to\/app', forward_to: '10.0.0.2:4000' do |modified, added, removed|\n # After broadcasting the changes to any connected recipients,\n # this block will still be called\nend\nlistener.start\nsleep\n<\/code><\/pre>\nAs a convenience, the listen<\/code> script is supplied which listens to a directory and forwards the events to a network address<\/p>\nlisten -f \"10.0.0.2:4000\" # changes in current directory are sent as absolute paths\nlisten -r -f \"10.0.0.2:4000\" # changes in current directory are sent as relative paths\nlisten -v -d \"\/projects\/my_project\" -f \"10.0.0.2:4000\" # changes in given directory are also shown\n<\/code><\/pre>\nNOTE: if you are using a gem like guard<\/code> and the paths on host and guest are not exactly the same, you\u2019ll generally want to use the -r<\/code> option for relative paths<\/em><\/p>\nTo connect to a broadcasting listener as a recipient, specify its address using Listen.on<\/code>:<\/p>\nlistener = Listen.on '10.0.0.2:4000' do |modified, added, removed|\n # This block will be called\nend\nlistener.start\nsleep\n<\/code><\/pre>\nSecurity considerations<\/h3>\n
Since file events potentially expose sensitive information, care must be taken when specifying the broadcaster address. It is recommended to always<\/strong> specify a hostname and make sure it is as specific as possible to reduce any undesirable eavesdropping.<\/p>\nDevelopment<\/h2>\n\n- Documentation hosted at RubyDoc.<\/li>\n
- Source hosted at GitHub.<\/li>\n<\/ul>\n
Pull requests are very welcome! Please try to follow these simple rules if applicable:<\/p>\n
\n- Please create a topic branch for every separate change you make.<\/li>\n
- Make sure your patches are well tested. All specs must pass on Travis CI.<\/li>\n
- Update the Yard documentation.<\/li>\n
- Update the README.<\/li>\n
- Please do not change<\/strong> the version number.<\/li>\n<\/ul>\n
For questions please join us in our Google group or on #guard<\/code> (irc.freenode.net).<\/p>\nAcknowledgments<\/h2>\nAuthor<\/h2>\n
Thibaud Guillaume-Gentil (@thibaudgg)<\/p>\n
Contributors<\/h2>\n
https:\/\/github.com\/guard\/listen\/graphs\/contributors<\/p>\n","protected":false},"excerpt":{"rendered":"
The Listen gem listens to file modifications and notifies you about the changes. Known issues \/ Quickfixes \/ Workarounds Just head over here: https:\/\/github.com\/guard\/listen\/wiki\/Quickfixes,-known-issues-and-workarounds Tips and Techniques Make sure you know these few basic tricks: https:\/\/github.com\/guard\/listen\/wiki\/Tips-and-Techniques Features OS-optimized adapters on MRI for Mac OS X 10.6+, Linux, *BSD and Windows, more info below. Detects file […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-7678","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/posts\/7678","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/comments?post=7678"}],"version-history":[{"count":0,"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/posts\/7678\/revisions"}],"wp:attachment":[{"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/media?parent=7678"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/categories?post=7678"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/unknownerror.org\/index.php\/wp-json\/wp\/v2\/tags?post=7678"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}