If you try rails new foo to build a new Rails application with RubyGems 1.8.23 and Ruby 1.9.3-p194 you'll get an error because RubyGems now verifies SSL certificates and Bundler tries to connect with when you build a new Rails app and is wrongly configured for SSL connections.
- Rubygems Issues For Mac Computers
- Questions / Discussion Area - RubyGems.org Support
- How To Install And Run Ruby On Mac OS X - Dummies
- Rubygems Issues For Mac Os
- OS-optimized adapters on MRI for Mac OS X 10.6+, Linux,.BSD and Windows, more info below. Detects file modification, addition and removal. You can watch multiple directories. Regexp-patterns for ignoring paths for more accuracy and speed; Increased change detection accuracy on OS X HFS and VFAT volumes. Tested on selected Ruby environments via.
- The RubyGems software allows you to easily download, install, and use ruby software packages on your system. The software package is called a “gem” which contains a packaged Ruby application or library. Gems can be used to extend or modify functionality in Ruby applications. Commonly they’re used to distribute reusable functionality that.
The
listen
gem listens to file modifications and notifies you about the changes.Listen
is currently accepting more maintainers. Please read this if you're interested in joining the team.Features
- OS-optimized adapters on MRI for Mac OS X 10.6+, Linux, *BSD and Windows, more info below.
- Detects file modification, addition and removal.
- You can watch multiple directories.
- Regexp-patterns for ignoring paths for more accuracy and speed
- Increased change detection accuracy on OS X HFS and VFAT volumes.
- Continuous Integration: tested on selected Ruby environments via Github Workflows.
Issues / limitations
- Limited support for symlinked directories (#279):
- Symlinks are always followed (#25).
- Symlinked directories pointing within a watched directory are not supported (#273- see Duplicate directory errors).
- No directory/adapter-specific configuration options.
- Support for plugins planned for future.
- TCP functionality was removed in
listen
3.0.0 (#319, #218). There are plans to extract this feature to separate gems (#258), until this is finished, you can use by locking thelisten
gem to version'~> 2.10'
. - Some filesystems won't work without polling (VM/Vagrant Shared folders, NFS, Samba, sshfs, etc.).
- Specs suite on JRuby and Rubinius aren't reliable on Travis CI, but should work.
- Windows and *BSD adapter aren't continuously and automatically tested.
- OSX adapter has some performance limitations (#342).
- FreeBSD users need patched version of rb-kqueue (as of 2020/11). See #475 for the issue, mat813/rb-kqueue#12 for the patch, and Bug 250432 in bugzilla.
- Listeners do not notify across forked processes, if you wish for multiple processes to receive change notifications you must listen inside of each process.
Pull requests or help is very welcome for these.
Install
The simplest way to install
listen
is to use Bundler.Complete Example
Here is a complete example of using the
listen
gem:Running the above in the background, you can see the callback block being called in response to each command:
Usage
Call
Listen.to
with one or more directories and the 'changes' callback passed as a block.Changes Callback
Changes to the listened-to directories are reported by the listener thread in a callback.The callback receives three array parameters:
modified
, added
and removed
, in that order.Each of these three is always an array with 0 or more entries.Each array entry is an absolute path.Pause / unpause / stop
Listeners can also be easily paused/unpaused:
Note: While paused,
listen
keeps on collecting changes in the background - to clear them, call stop
.Note: You should keep track of all started listeners and
stop
them properly on finish.Ignore / ignore!
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
option/method or overwrite default with ignore!
option/method.Note:
:ignore
regexp patterns are evaluated against relative paths.Rubygems Issues For Mac Computers
Note: Ignoring paths does not improve performance, except when Polling (#274).
Only
Listen
watches all files (less the ignored ones) by default. If you want to only listen to a specific type of file (i.e., just .rb
extension), you should use the only
option/method.Note:
:only
regexp patterns are evaluated only against relative file paths.Options
All the following options can be set through the
Listen.to
after the directory path(s) params.Logging and Debugging
Listen
logs its activity to Listen.logger
.This is the primary method of debugging.Custom Logger
You can call
Listen.logger =
to set a custom listen
logger for the process. For example:Default Logger
If no custom logger is set, a default
listen
logger which logs to to STDERR
will be created and assigned to Listen.logger
.The default logger defaults to the
error
logging level (severity).You can override the logging level by setting the environment variable LISTEN_GEM_DEBUGGING=<level>
.For <level>
, all standard ::Logger
levels are supported, with any mix of upper-/lower-case:The default of
error
will be used if an unsupported value is set.Note: The alternate values
1
, 2
, true
and yes
shown above are deprecated and will be removed from listen
v4.0.Disabling Logging
If you want to disable
listen
logging, setListen Adapters
The
Listen
gem has a set of adapters to notify it when there are changes.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.
There is also a polling adapter - although it's much slower than other adapters,it works on every platform/system and scenario (including network filesystems such as VM shared folders).
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.The
listen
gem will choose the best adapter automatically, if present. If youwant to force the use of the polling adapter, use the :force_polling
optionwhile initializing the listener.On Windows
If you are on Windows, it's recommended to use the
wdm
adapter instead of polling.Please add the following to your Gemfile:
On *BSD
If you are on *BSD you can try to use the
rb-kqueue
adapter instead of polling.Please add the following to your Gemfile:
Getting the polling fallback message?
Please visit the installation section of the Listen WIKI for more information and options for potential fixes.
Issues and Troubleshooting
If the gem doesn't work as expected, start by setting
LISTEN_GEM_DEBUGGING=debug
or LISTEN_GEM_DEBUGGING=info
as described above in Logging and Debugging.NOTE: without providing the output after setting the
LISTEN_GEM_DEBUGGING=debug
environment variable, it is usually impossible to guess why listen
is not working as expected.See TROUBLESHOOTING
Performance
If
listen
seems slow or unresponsive, make sure you're not using the Polling adapter (you should see a warning upon startup if you are).Also, if the directories you're watching contain many files, make sure you're:
- not using Polling (ideally)
- using
:ignore
and:only
options to avoid tracking directories you don't care about (important with Polling and on MacOS) - running
listen
with the:latency
and:wait_for_delay
options not too small or too big (depends on needs) - not watching directories with log files, database files or other frequently changing files
- not using a version of
listen
prior to 2.7.7 - not getting silent crashes within
listen
(seeLISTEN_GEM_DEBUGGING=debug
) - not running multiple instances of
listen
in the background - using a file system with atime modification disabled (ideally)
- not using a filesystem with inaccurate file modification times (ideally), e.g. HFS, VFAT
- not buffering to a slow terminal (e.g. transparency + fancy font + slow gfx card + lots of output)
- ideally not running a slow encryption stack, e.g. btrfs + ecryptfs
When in doubt,
LISTEN_GEM_DEBUGGING=debug
can help discover the actual events and time they happened.See also Tips and Techniques.
Development
- Documentation hosted at RubyDoc.
- Source hosted at GitHub.
Pull requests are very welcome! Please try to follow these simple rules if applicable:
Questions / Discussion Area - RubyGems.org Support
- Please create a topic branch for every separate change you make.
- Make sure your patches are well tested. All specs must pass on Travis CI.
- Update the Yard documentation.
- Update the README.
- Please do not change the version number.
For questions please join us in our Google group or on
#guard
(irc.freenode.net).Releasing
Prerequisites
- You must have commit rights to the GitHub repository.
- You must have push rights for rubygems.org.
How to release
- Run
bundle install
to make sure that you have all the gems necessary for testing and releasing. - Ensure all tests are passing by running
bundle exec rake
. - Determine which would be the correct next version number according to semver.
- Update the version in
./lib/listen/version.rb
. - Update the version in the Install section of
./README.md
(gem 'listen', '~> X.Y'
). - Commit the version in a single commit, the message should be 'Preparing vX.Y.Z'
- Run
bundle exec rake release:full
; this will tag, push to GitHub, and publish to rubygems.org. - Update and publish the release notes on the GitHub releases page if necessary
Acknowledgments
- Michael Kessler (netzpirat) for having written the initial specs.
- Travis Tilley (ttilley) for this awesome work on fssm & rb-fsevent.
- Natalie Weizenbaum (nex3) for rb-inotify, a thorough inotify wrapper.
- Mathieu Arnold (mat813) for rb-kqueue, a simple kqueue wrapper.
- Maher Sallam for wdm, 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)
Contributors
Installation of Jekyll on Mac is usually less problematic than on Windows. However, you may run into permissions issues with Ruby that you must overcome. You should also use Bundler to be sure that you have all the required gems and other utilities on your computer to make the project run.
Ruby and RubyGems
Ruby and RubyGems are usually installed by default on Macs. Open your Terminal and type
which ruby
and which gem
to confirm that you have Ruby and Rubygems. You should get a response indicating the location of Ruby and Rubygems.If you get responses that look like this:
and
Great! Skip down to the Bundler section.
However, if your location is something like
/Users/MacBookPro/.rvm/rubies/ruby-2.2.1/bin/gem
, which points to your system location of Rubygems, you will likely run into permissions errors when trying to get a gem. A sample permissions error (triggered when you try to install the jekyll gem such as gem install jekyll
) might look like this for Rubygems:Instead of changing the write permissions on your operating system’s version of Ruby and Rubygems (which could pose security issues), you can install another instance of Ruby (one that is writable) to get around this.
Install Homebrew
Homebrew is a package manager for the Mac, and you can use it to install an alternative instance of Ruby code. To install Homebrew, run this command:
If you already had Homebrew installed on your computer, be sure to update it:
Install Ruby through Homebrew
How To Install And Run Ruby On Mac OS X - Dummies
Now use Homebrew to install Ruby:
Log out of terminal, and then then log back in.
When you type
which ruby
and which gem
, you should get responses like this:And this:
Now Ruby and Rubygems are installed under your username, so these directories are writeable.
Note that if you don’t see these paths, try restarting your computer or try installing rbenv, which is a Ruby version management tool. If you still have issues getting a writeable version of Ruby, you need to resolve them before installing Bundler.
Install the Jekyll gem
Rubygems Issues For Mac Os
At this point you should have a writeable version of Ruby and Rubygem on your machine.
Now use
gem
to install Jekyll:You can now use Jekyll to create new Jekyll sites following the quick-start instructions on Jekyllrb.com.
Installing dependencies through Bundler
Some Jekyll themes will require certain Ruby gem dependencies. These dependencies are stored in something called a Gemfile, which is packaged with the Jekyll theme. You can install these dependencies through Bundler. (Although you don’t need to install Bundler for this Documentation theme, it’s a good idea to do so.)
Bundler is a package manager for RubyGems. You can use it to get all the gems (or Ruby plugins) that you need for your Jekyll project.
You install Bundler by using the gem command with RubyGems:
If you’re prompted to switch to superuser mode (
sudo
) to get the correct permissions to install Bundler in that directory, avoid doing this. All other applications that need to use Bundler will likely not have the needed permissions to run.Bundler goes out and retreives all the gems that are specified in a Jekyll project’s Gemfile. If you have a gem that depends on other gems to work, Bundler will go out and retrieve all of the dependencies as well. (To learn more about Bundler, see About Ruby Gems.
The vanilla Jekyll site you create through
jekyll new my-awesome-site
doesn’t have a Gemfile, but many other themes (including the Documentation theme for Jekyll) do have a Gemfile.Serve the Jekyll Documentation theme
- Browse to the directory where you downloaded the Documentation theme for Jekyll.
- Type
jekyll serve
- Go to the preview address in the browser. (Make sure you include the
/
at the end.)