Every project we start now, we have been utilizing Sass, Compass, and several Ruby gems that Team Sass has been busy developing. Now that we have several projects going on at once, it became clear that we had to have a method of ensuring all our of ruby gems are consistant across projects and environments. As we start new projects, we want to use the latest Compass extensions, but some of our older projects require previous versions of the gems— and we are developing these projects all on the same machines.

Luckily, Ruby gem versions can be easily managed by the Bundler gem, and the version of Ruby can be kept clean with rbenv. These two tools will create files to be committed to version control, so that everybody working on the project will be using consistant versions of gems. To have all of these tools, it takes a small amount of local setup but it is well worth the time.

Installation

This first portion will only have to be run once. If you want or need to use multiple versions of Ruby, or have developers who are on the project, start from the beginning. If not, you can just install Bundler.

Homebrew

First off, to install rbenv, you will need homebrew installed and updated on your Mac. Homebrew is a package manager for Mac, and allows you to install other packages that are not included in OS X. If you have not installed Homebrew before, open up your terminal and run:


ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"
echo "export PATH=/usr/local/bin:$PATH" >> ~/.bash_profile


The first line will install Homebrew, the second will allow the programs that Homebrew installs to be run.

We can then check to make sure Homebrew is installed correctly by running


brew doctor


If Homebrew detects any issues, it will tell you what is wrong. Occasionally, it will also tell you how to fix it. If not, usually a quick google search will let you know what needs to happen. After the Homebrew installation is running well, make sure Homebrew is pulling the most update-to-date information by running:


brew update


Voila! Homebrew is installed and running at full steam.

rbenv

If you are a developer that needs different versions of ruby on your machine, or has a need to update your machine’s local version or ruby, then rbenv is for you. In my opinion, it is much easier, and faster to use than Ruby Version Manager (RVM). As a special note, rbenv and RVM do not play well together, and you cannot have both installed on your machine. If your machine has RVM currently installed, then you will have to completely remove it before installing rbenv.

To install rbenv, all you need is to run the Homebrew installation, then add a line to your .bash_profile file. The following two lines of code will do the trick.

brew install rbenv ruby-build
echo 'eval "$(rbenv init -)"' >> ~/.bash_profile


Now that you have rbenv installed, you can select which version of Ruby you want to use in your projects. It will allow you to have different versions of Ruby installed, and have each project specify which version of Ruby it needs. To see a list of all available versions of Ruby, use the command rbenv install --list. You can then install any version you want by running:


rbenv install {{version number}
rbenv rehash


The rbenv rehash MUST be run every time you install a new version. I recommend installing the default version of Ruby on OS X Mountain Lion, so that you have a baseline for projects that have already been started. I had a small bug when I installed the right version into rbenv, but the following lines of code should allow you to install it without issue:


rbenv install 1.8.7-p358 CONFIGURE_OPTS="--without-tk"
rbenv rehash


Once you install multiple versions of Ruby with rbenv, you can set the global version you want to use on your machine with rbenv global {{version number}} or if you want to override the version of Ruby you are using within your terminal window you can use rbenv shell {{version number}}.

Bundler

Bundler will allow you to specify exactly which version of a Ruby gem you want to use in your project, and allow you to use different versions for different projects. You will need to install it for each version of ruby you install with rbenv. If you are not using rbenv, you will only need to install it once. All you need to run is:


gem install bundler

If you are using rbenv, also run:

rbenv rehash


Since Bundler will install different versions of Ruby gems for different projects, it helps to just allow it to download the specific gem files to the project directory. Then that one folder should be removed from source control, as the gem versions will be specified by Bundler. To change this configuration, run these commands:


mkdir ~/.bundle
echo 'BUNDLE_PATH: vendor/bundle' >> ~/.bundle/config


This will have all of your gem files be in “{{project directory}}/vendor/bundle”, but you can change the folder to something else if your project requires it.

Make Gems Install Faster

Unless you need your Ruby gem documentation to be stored locally, you can save a lot of time when you download new gems by not downloading the full documentation. Just run this to add a line to your .gemrc file.


echo 'gem: --no-rdoc --no-ri' >> ~/.gemrc


Usage

Once rbenv and Bundler have been installed, using them is easy!

rbenv

Select which version of Ruby you want in your project, and within your project folder run the command rbenv local {{version number}}. This will create a “.ruby_version” file that rbenv and RVM will both use to select which version of Ruby to use. Make sure you commit the “.ruby_version” file to source control!.

Bundler

Once you have started your project, you can lock the specific versions of Ruby gems you want to use with Bundler. Simply run bundle install, and all of the Ruby gems you are using will be saved to your “vendor/bundle” folder. Bundler will then create a “Gemfile.lock” file that will specify for other users what version of a gem to use. Once another developer joins the project, all they have to run is bundle install, and the exact same versions of the gem will be installed on their machine. Finally, to ensure you are using the Bundler versions of the gems, run bundle exec {{command}}. For example, if you have a compass project, you would run:

To compile once:

bundle exec compass compile

To watch the Sass files:

bundle exec compass watch


By running you commands through Bundler, you will be ensured to have the same gem versions that are found in the Gemfile.lock file.

Wrap Up