Skip to content


Repository files navigation


A Ruby gem for file based mutexes with a simple external process management wrapper.


The Mutagem library provides file based mutexes for recursion protection and wrapper classes for external processes with support for output and exit status capturing.

A test suite is provided for both unit testing with RSpec and functional testing with Cucumber. Mutagem development was jump-started by cloning BasicGem.

Example Usage

The following Ruby code is used to run a word by word diff on two folders of comma delimited data. Each folder contains before and after CSV dumps from a SQL database. The CSV files have the same name in each of the two folders.

Mutagem is providing recursion protection. The recursion protection is very useful if the script is run in an automated environment (ex. cron). Mutagem is also capturing output and exit status for the diff processes allowing customized output.

Standard diff is quick but it can't give you a word by word diff of CSV data. Word by word colorized diffing with support for custom delimiters is provided by dwdiff.

#!/usr/bin/env ruby

require 'rubygems'
require 'mutagem'
require 'pathname'
require 'term/ansicolor'

class String
  include Term::ANSIColor

lock_was_sucessful ='diff.lck').execute do

  $stdout.sync = true # force screen updates
  before_files = Dir.glob('test/dump/before/*.csv')

  before_files.each do |bf|

    af = 'test/dump/after/' +

    # quick diff
    cmd = "diff #{bf} #{af}"
    task =

    if (task.exitstatus == 0)
      # no changes, show a "still working" indicator
      print ".".green
      # we have changes, slow diff, word based and CSV (comma) sensitive
      print "D".red
      puts "\n#{af}"

      cmd = "dwdiff --color --context=0 --delimiters=, #{bf} #{af}"
      task =

      puts task.output

  puts "\n"

puts "process locked" unless lock_was_sucessful

System Requirements

  • POSIX system (tested on Linux and Windows/Cygwin environments)


Mutagem is avaliable on

gem install mutagem


Development dependencies require Ruby 1.9.3

Mutagem uses Bundler to manage dependencies, the gemspec file is maintained by hand.

git clone
cd mutagem

Use bundle to install development dependencies

bundle install

rake -T

rake build         # Build mutagem-0.1.2.gem into the pkg directory
rake features      # Run Cucumber features
rake install       # Build and install mutagem-0.1.2.gem into system gems
rake release       # Create tag v0.1.2 and build and push mutagem-0.1.2.gem to Rubygems
rake spec          # Run specs
rake test          # Run specs and features


Copyright (c) 2010-2017 GearheadForHire, LLC. See LICENSE for details.


File based mutexes with a simple external process management wrapper







No packages published