Forward filesystem change notifications to your Vagrant VM.
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.
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
This leverages the speed of using real filesystem events while still being general enough to don't require any support from applications.
Due to the nature of filesystem events and the fact that
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
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.
vagrant-fsnotify is a Vagrant plugin and can be installed by
$ vagrant plugin install vagrant-fsnotify
Vagrant version 1.7.3 or greater is required.
Vagrantfile synced folder configuration, add the
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.
In multi-VM environments, you can specify the name of the VMs targeted by
$ vagrant fsnotify <vm-name-1> <vm-name-2> ...
To exclude files or directories from being watched, you can add an
option, which takes an array of strings (matched as a regexp against relative
config.vm.synced_folder ".", "/vagrant", fsnotify: true, exclude: ["path1", "some/directory"]
This will exclude all files inside the
some/directory. It will
also exclude files such as
Guest path override
If your actual path on the VM is not the same as the one in
example when using
vagrant-bindfs, you can use the
config.vm.synced_folder ".", "/vagrant", fsnotify: true, override_guestpath: "/real/path"
This will forward a notification on
/real/path/myfile instead of
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:
For example, to forward only added files events to the default
folder, add the following to the
config.vm.synced_folder ".", "/vagrant", fsnotify: [:added]