Ruby Weekly is a weekly newsletter covering the latest Ruby and Rails news.

Watchr – More Than An Automated Test Runner

By Joe Fiorini / March 29, 2011

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

def upload_template(file) = "http://{key}:{secret}@{domain}"
  asset = ShopifyAPI::Asset.find(file)
  asset.value =

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 and tweets as


  1. Scott Becker says:

    I've used the directory_watcher gem to do similar things. Do you know if there is any difference between the watchr and directory_watcher Gems? Is there any advantage of one vs the other?

  2. Ryan Bates says:

    How does this compare to guard?

  3. Joe Fiorini says:

    Guard looks cool, but a little more overhead to get started. Way more powerful though, given the SIG handlers, etc. Perhaps Guard is to Watchr as Rails is to Sinatra?

  4. Mikko Lehtonen says:

    This looks rather nice! So far I've used a little C program I've made for my own uses, Autobuild. It matches my simpler use-cases just fine. Though it currently supports only osx and win32.

  5. Pingback: Watchr 不只是 Continuous Testing | ihower { blogging }

  6. Jack Dempsey says:

    At first I didn't like Guard, and stayed with watchr for most tasks. Over time it grew on me, and now often use Guard for rails projects, watchr for simpler tasks. I think the Sinatra/Rails analogy is apt--both have a place and a great pieces of software. Thanks for the article Joe.

  7. Nate Klaiber says:

    But who watches the watchr? :)

    Great article, Joe. I like your implementation and use case for Shopify.

Other Posts to Enjoy

Twitter Mentions