(The) Bundler

Touted by its developers as "the best way to manage your application's dependencies", Bundler is one of the most often used tools in Ruby/Rails developer's toolbox. As usual, this tool too has a "lifecycle" of its own (the steps to be followed from initialization of the tool parameters, the current usage, and - where the case - the closing/termination of the process).

So, for Bundler, the relevant steps are as follows:


1. Installation

First of all, in your project directory, you should have a Gemfile file, which contains all the gems needed by your application (each gem is declared with a line lilke gem 'gemname'  - but much more complex options are available - such as requiring an exact version of the gem, a minimal version of the gem, creating groups of gems which are loaded selectively, etc.)

Then, run (I assume the gem installation was already done with gem install bundler):

    bundle install

Now, there are two cases:

a. If in your project directory there isn't a Gemfile.lock file, this will be created. Basically, the Bundler looks for all needed gems dependencies, and creates the .lock file which contains ALL the gems needed for your application to run properly. This case is actually meaning that you are the author of the application, you already have the gems installed on your machine, and want the rest of the world know what they should have in order to run it successfully.

b. If in your project directory there is a Gemfile.lock, then the Bundler will look for all needed/declared gems and will install them (from the source declared in the Gemfile, typically source 'https://rubygems.org'). This case is actually meaning you have downloaded/cloned the application from somewhere else, and now you want to prepare your Ruby environment in order to run properly.

An interesting version of the command (very often used) is:

    bundle install --without production

Which actually tells the Bundler to install ALL the gems, BUT the ones declared in the production group (useful if we think that, for instance, we may want for production to use PostgreSQL, which we may even not have installed on our machine).


2. Checking and updating

In order to see the current state of affairs with your installed gems, you can:

    bundle check (that will tell you whether or not the requirements for your app are met)

    bundle show (similar to bundle list, it will tell you what are the gems and versions actually used)

    bundle outdated (self-explanatory, I guess...)


In order to update the gems installed, run:

    bundle update


3. Running gem-related commands using the bundler

First, the command:

    bundle exec command

Now, the rationale: imagine that you carefully build an application using version x of a gem - only to find out that there is a new, better version y of the gem (we assume no RVM, more about this in a future post). You update the gem (with gem update [gemname], as indicated in a previous post). All well, only to find out that your app stopped working with the new gem version.

In order to avoid such unpleasant situations, many gems have a self-control which prevents them from being used on a wrong version (instead of running, they will issue a "command_name aborted" warning. In order to make sure you use the command with the exact version of the gem that is required by your app environment, one has to prefix the command with the bundle exec.

The end result can look discouraging to newbies (yes, I've been there...) which sometimes feel they have to read from a book of spells in order to make Ruby/Rails work. Something like this:

    bundle exec rake db:seed

(I haven't said yet anything about rake, but this is going to happen soon enough :-)).


4. Oh, and I almost forgot:

    bundle help


Web reference: http://gembundler.com/