vagrant-fsnotify

by adrienkohlbecker

adrienkohlbecker / vagrant-fsnotify

Forward filesystem change notifications to your Vagrant VM

126 Stars 12 Forks Last release: Not found MIT License 55 Commits 11 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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:

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   ...

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]

Development

To hack on

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

Then, after cloning the repo: ```shell

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.