Watchr is a development tool that monitors a directory tree and triggers a user defined action (in Ruby) whenever an observed file is modified. Its most typical use is continuous testing, and as such it is a more flexible alternative to autotest. It is maintained by Martin Aumont and available on GitHub.

Watchr works by allowing you to specify the path to the file or files you want to monitor. When the file is changed it executes whatever block of Ruby code you give it. As the README states its most common use case is as a replacement for autotest. After using Watchr for a couple years now, I have learned that it’s much more than that. For example, it has helped me automatically copy a setup script to a virtual machine while building it and to update large blocks of content in a database.

How I Used Watchr to Automate Shopify Theme Development

I recently started a Shopify project with a colleague (Shopify is a hosted platform for building ecommerce sites). Users can edit their store’s look and feel through a web-based admin interface. This may work for most shop owners, but I’ve grown accustomed to editing text in Vim and working at the command line. Fortunately, Shopify has a very nice API for uploading templates to your store. Watchr to the rescue! I fired up my editor and not long after I had a very helpful script:

require 'shopify_api'

watch('templates/.*.liquid') do |match|
  puts "Updating #{match[0].inspect}..."
  upload_template(match.to_s)
end

def upload_template(file)
  ShopifyAPI::Base.site = "http://{key}:{secret}@{domain}.myshopify.com/admin/"
  asset = ShopifyAPI::Asset.find(file)
  asset.value = File.read(file)
  asset.save
end

With this script all I have to do is save the file I’m working on and Watchr uploads it to Shopify for me. How does it work? The directory structure on my file system mirrors Shopify’s template structure. All my script has to do is read the file and send the path and contents to the server. Watchr uses OSX’s native File System Events API to listen for changes to files matching the path string I pass into watch. When a matching file changes, it executes the block and hands in the path to the changed file (or files).

These simple Watchr scripts have saved me time and, more importantly, frustration. With just a few lines of code I can automate away tedious parts of my day while following my preferred workflow and not compromise efficiency. Watchr is not just about running my tests, it’s about improving my workflow as much as possible.

More Info

Want some more information? Check out Watchr on Github, check out the docs, or read the wiki for some more examples. When you’re ready to get started run gem install watchr and write your first script.

Editor’s note: I just noticed that Ric Roberts wrote Watchr: A Flexible, Generic Alternative to AutoTest for Ruby Inside back in 2009. You might find that post useful too.

Joe is a Software Craftsman at LeanDog Software where he helps run their Ruby
delivery practice on a boat in Cleveland, OH. He blogs about
software-related topics at http://blog.densitypop.com and tweets as
@joefiorini