Windows Directory Monitor (WDM)

Windows Directory Monitor (WDM) is a thread-safe ruby library which can be used to monitor directories for changes on Windows.

It's mostly implemented in C and uses the Win32 API for a better performance.

If you are using Bundler, add the following line to your application's Gemfile:

gem 'wdm'

Although wdm is only usable on Windows, it can be installed on Linux and Macos as well, so that no :platform option is necessary. Then execute:

$ bundle

Or install it yourself as:

$ gem install wdm

For a simple example on how to use WDM, you can take a look at the example directory of the repository.

You can find a comparison of different ruby libraries for watching directory changes on Windows in the benchmark directory of the repository.

To start watching directories, you need an instance of WDM::Monitor:

require "wdm"
monitor = WDM::Monitor.new

After that, register a callback for each directory you want to watch:

# Watch a single directory
monitor.watch('C:\Users\Maher\Desktop') { |change|  puts change.path }

# Watch a directory with its subdirectories
monitor.watch_recursively('C:\Users\Maher\Projects\my_project') { |change|  puts change.path }

Both Monitor#watch and Monitor#watch_recursively can take a series of options after the first parameter to specify the watching options:

# Report changes to directories in the watched directory (Ex.: Addition of an empty directory)
monitor.watch('C:\Users\Maher\Desktop', :default, :directories)

The supported options are:

These options map to the filters that ReadDirectoryChangesW takes in its dwNotifyFilter parameter. You can find more info on the docs page of ReadDirectoryChangesW.

Now all that's left to be done is to run the monitor:

monitor.run!

The Monitor#run! method blocks the process. Since monitors are thread-safe, you can run them in a thread if you don't want to block your main one:

worker_thread = Thread.new { monitor.run! }

# The process won't block; it will continue with the next line of code...

When you are done with the monitor, don't forget to stop it. Here is a snippet to always stop the monitor when the ruby process exits:

at_exit { monitor.stop }

The passed argument to the block is an instance of WDM::Change. This class has two methods:

• Change#path: The absolute path to the change.
• Change#type: This can be one of the following values: :added, :modified, :removed, :renamed_old_file or :renamed_new_file.

Download the source, then run the following:

$ bundle exec rake compile

To get debug messages, you need to enable them like so:

$ bundle exec rake clean compile -- --with-cflags=-DWDM_DEBUG_ENABLED=TRUE

$ bundle exec rake spec

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Add a spec for your change
4. Commit your changes (git commit -am 'Added some feature')
5. Push to the branch (git push origin my-new-feature)
6. Create new Pull Request
7. Ensure CI runs green.

Maher Sallam