vagrant-fsnotify

Forward filesystem change notifications to your Vagrant VM.

Problem

Some filesystems (e.g. ext4, HFS+) have a feature of event notification. Interested applications can subscribe and are notified when filesystem events happen (e.g. a file was created, modified or deleted).

Applications can make use of this system to provide features such as auto-reload or live updates. For example, Jekyll regenerates the static website and Guard triggers a test run or a build when source files are modified.

Unfortunately, Vagrant users have a hard time making use of these features when the application is running inside a virtual machine. When the file is modified on the host, the event is not propagated to the guest and the auto-reload never happens.

There are several bug reports related to this issue:

• https://www.virtualbox.org/ticket/10660
• guard/listen#53
• guard/listen#57
• guard/guard#269
• hashicorp/vagrant#707

There are two generally accepted solutions. The first is fall back to long polling, the other is to forward the events over TCP. The problem with long polling is that it's painfully slow, especially in shared folders. The problem with forwarding events is that it's not a general approach that works for any application.

Solution

vagrant-fsnotify proposes a different solution: run a process listening for filesystem events on the host and, when a notification is received, access the virtual machine guest and touch the file in there (or touch followed by a rm in case of file removals), causing an event to be propagated on the guest filesystem.

This leverages the speed of using real filesystem events while still being general enough to don't require any support from applications.

Caveats

Due to the nature of filesystem events and the fact that vagrant-fsnotify uses touch, the events are triggerred back on the host a second time. To avoid infinite loops, we add an arbitrary debounce of 2 seconds between touch-ing the same file. Thus, if a file is modified on the host more than once in 2 seconds the VM will only see one notification. If the second trigger on the host or this arbitrary debounce is unacceptable for your application, vagrant-fsnotify might not be for you.

Installation

vagrant-fsnotify is a Vagrant plugin and can be installed by running:

$ vagrant plugin install vagrant-fsnotify

Vagrant version 1.7.3 or greater is required.

Usage

Basic setup

In Vagrantfile synced folder configuration, add the fsnotify: true option. For example, in order to enable vagrant-fsnotify for the the default /vagrant shared folder, add the following:

config.vm.synced_folder ".", "/vagrant", fsnotify: true

When the guest virtual machine is up, run the following:

$ vagrant fsnotify

This starts the long running process that captures filesystem events on the host and forwards them to the guest virtual machine.

Run automatically on vagrant up

To have vagrant fsnotify start automatically with your guest, you can use triggers. Add this to your Vagrantfile:

  config.trigger.after :up do |t|
    t.name = "vagrant-fsnotify"
    t.run = { inline: "vagrant fsnotify" }
  end

Now, whenever you run vagrant up, vagrant fsnotify will be run as well. Learn more at https://www.vagrantup.com/docs/triggers/

Multi-VM environments

In multi-VM environments, you can specify the name of the VMs targeted by vagrant-fsnotify using:

$ vagrant fsnotify <vm-name-1> <vm-name-2> ...

Excluding files

To exclude files or directories from being watched, you can add an :exclude option, which takes an array of strings (matched as a regexp against relative paths):

config.vm.synced_folder ".", "/vagrant", fsnotify: true,
                                         exclude: ["path1", "some/directory"]

This will exclude all files inside the path1 and some/directory. It will also exclude files such as another/directory/path1

Guest path override

If your actual path on the VM is not the same as the one in synced_folder, for example when using vagrant-bindfs, you can use the :override_guestpath option:

config.vm.synced_folder ".", "/vagrant", fsnotify: true,
                                         override_guestpath: "/real/path"

This will forward a notification on ./myfile to /real/path/myfile instead of /vagrant/myfile.

Select filesystem events

By default, when the :fsnotify key in the Vagrantfile is configured with true, all filesystem events are forwarded to the VM (i.e. file creation, modification and removal events). If, instead, you want to select only a few of those events to be forwarded (e.g. you don't care about file removals), you can use an Array of Symbols among the following options: :added, :modified and :removed.

For example, to forward only added files events to the default /vagrant folder, add the following to the Vagrantfile:

config.vm.synced_folder ".", "/vagrant", fsnotify: [:added]

Set touch flags

By default, the touch command on the VM will be run with modification flag and access flag, setting both modification and access attributes of the file. If only either flag should be used the :touch param can be set per machine config in the Vagrantfile. The param supports an array with either or both :modification and :access values.

As example, to only set the access attribute of files when they have changed on the host system set the following in the Vagrantfile:

config.fsnotify.touch = [:access]

or for instances and providers

config.vm.define "vm" do |instance|
    instance.fsnotify.touch = [:access]
end

Development

To hack on vagrant-fsnotify, you need a recent ruby and virtualbox installed.

Then, after cloning the repo:

# install development gems
bundle install

# run vagrant commands by prefixing them with `bundle exec` to run with the plugin installed from source
# this will launch a basic ubuntu VM and monitor file changes on the current directory
bundle exec vagrant up

# make changes to the code
vim lib/vagrant-fsnotify/command-fsnotify.rb
...

# relaunch the process to activate your changes
bundle exec vagrant fsnotify

Original work

This plugin used vagrant-rsync-back by @smerill and the Vagrant source code as a starting point.