11.2. Bundler

In a Rails project, different gems are used (see Section 11.1, “Gems”) and a developer can also add further gems. Bundler helps the developer to install all these gems in the right version and to take into account important dependencies. In previous Rails versions, you as developer had to always call a bundle install after a rails new. Now, this is done automatically within rails new. In the output you can see which gems are installed by bundle install:
$ rails new webshop
  [...]
       run  bundle install
Fetching gem metadata from https://rubygems.org/..........
Fetching gem metadata from https://rubygems.org/..
Resolving dependencies...
Using rake (10.1.0) 
Using i18n (0.6.4) 
Using minitest (4.7.5) 
Using multi_json (1.7.7) 
Using atomic (1.1.10) 
Using thread_safe (0.1.0) 
Using tzinfo (0.3.37) 
Using activesupport (4.0.0) 
Using builder (3.1.4) 
Using erubis (2.7.0) 
Using rack (1.5.2) 
Using rack-test (0.6.2) 
Using actionpack (4.0.0) 
Using mime-types (1.23) 
Using polyglot (0.3.3) 
Using treetop (1.4.14) 
Using mail (2.5.4) 
Using actionmailer (4.0.0) 
Using activemodel (4.0.0) 
Using activerecord-deprecated_finders (1.0.3) 
Using arel (4.0.0) 
Using activerecord (4.0.0) 
Using bundler (1.3.5) 
Using coffee-script-source (1.6.3) 
Using execjs (1.4.0) 
Using coffee-script (2.2.0) 
Using thor (0.18.1) 
Using railties (4.0.0) 
Using coffee-rails (4.0.0) 
Using hike (1.2.3) 
Using jbuilder (1.4.2) 
Using jquery-rails (3.0.4) 
Using json (1.8.0) 
Using tilt (1.4.1) 
Using sprockets (2.10.0) 
Using sprockets-rails (2.0.0) 
Using rails (4.0.0) 
Using rdoc (3.12.2) 
Using sass (3.2.9) 
Using sass-rails (4.0.0) 
Using sdoc (0.3.20) 
Using sqlite3 (1.3.7) 
Using turbolinks (1.3.0) 
Using uglifier (2.1.2) 
Your bundle is complete!
Use `bundle show [gemname]` to see where a bundled gem is installed.
$ cd webshop 
$ 
The file Gemfile generated by rails new indicates which gems are to be installed by Bundler:
source 'https://rubygems.org'

# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
gem 'rails', '4.0.0'

# Use sqlite3 as the database for Active Record
gem 'sqlite3'

# Use SCSS for stylesheets
gem 'sass-rails', '~> 4.0.0'

# Use Uglifier as compressor for JavaScript assets
gem 'uglifier', '>= 1.3.0'

# Use CoffeeScript for .js.coffee assets and views
gem 'coffee-rails', '~> 4.0.0'

# See https://github.com/sstephenson/execjs#readme for more supported runtimes
# gem 'therubyracer', platforms: :ruby

# Use jquery as the JavaScript library
gem 'jquery-rails'

# Turbolinks makes following links in your web application faster. Read more: https://github.com/rails/turbolinks
gem 'turbolinks'

# Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder
gem 'jbuilder', '~> 1.2'

group :doc do
  # bundle exec rake doc:rails generates the API under doc/api.
  gem 'sdoc', require: false
end

# Use ActiveModel has_secure_password
# gem 'bcrypt-ruby', '~> 3.0.0'

# Use unicorn as the app server
# gem 'unicorn'

# Use Capistrano for deployment
# gem 'capistrano', group: :development

# Use debugger
# gem 'debugger', group: [:development, :test]
The format used is easy to explain: the word gem is followed by the name of the gem and then, if required, a specification of the version of the gem.
For example, the line gem 'rails', '4.0.0' stands for "install the gem with the name rails in the version 4.0.0".
With ~> before the version number you can determine that the newest version after this version number should be installed. As a result, the last digit is incremented, so for example gem 'rails', '~> 4.0.0' would correspondingly install a Rails 4.0.1, but not a 4.1 (for the latter, you would need to specify gem 'rails', '~> 4.0').

Buy the new Rails 5.1 version of this book.

You have the option of installing certain gems only in certain environments. To do so, you need to enclose the corresponding lines in a group :name do loop.
Apart from the file Gemfile there is also the file Gemfile.lock and the exact versions of the installed gems are listed there. In the above example, it looks like this:
GEM
  remote: https://rubygems.org/
  specs:
    actionmailer (4.0.0)
      actionpack (= 4.0.0)
      mail (~> 2.5.3)
    actionpack (4.0.0)
      activesupport (= 4.0.0)
      builder (~> 3.1.0)
      erubis (~> 2.7.0)
      rack (~> 1.5.2)
      rack-test (~> 0.6.2)
    activemodel (4.0.0)
      activesupport (= 4.0.0)
      builder (~> 3.1.0)
    activerecord (4.0.0)
      activemodel (= 4.0.0)
      activerecord-deprecated_finders (~> 1.0.2)
      activesupport (= 4.0.0)
      arel (~> 4.0.0)
    activerecord-deprecated_finders (1.0.3)
    activesupport (4.0.0)
      i18n (~> 0.6, >= 0.6.4)
      minitest (~> 4.2)
      multi_json (~> 1.3)
      thread_safe (~> 0.1)
      tzinfo (~> 0.3.37)
    arel (4.0.0)
    atomic (1.1.10)
    builder (3.1.4)
    coffee-rails (4.0.0)
      coffee-script (>= 2.2.0)
      railties (>= 4.0.0.beta, < 5.0)
    coffee-script (2.2.0)
      coffee-script-source
      execjs
    coffee-script-source (1.6.3)
    erubis (2.7.0)
    execjs (1.4.0)
      multi_json (~> 1.0)
    hike (1.2.3)
    i18n (0.6.4)
    jbuilder (1.4.2)
      activesupport (>= 3.0.0)
      multi_json (>= 1.2.0)
    jquery-rails (3.0.4)
      railties (>= 3.0, < 5.0)
      thor (>= 0.14, < 2.0)
    json (1.8.0)
    mail (2.5.4)
      mime-types (~> 1.16)
      treetop (~> 1.4.8)
    mime-types (1.23)
    minitest (4.7.5)
    multi_json (1.7.7)
    polyglot (0.3.3)
    rack (1.5.2)
    rack-test (0.6.2)
      rack (>= 1.0)
    rails (4.0.0)
      actionmailer (= 4.0.0)
      actionpack (= 4.0.0)
      activerecord (= 4.0.0)
      activesupport (= 4.0.0)
      bundler (>= 1.3.0, < 2.0)
      railties (= 4.0.0)
      sprockets-rails (~> 2.0.0)
    railties (4.0.0)
      actionpack (= 4.0.0)
      activesupport (= 4.0.0)
      rake (>= 0.8.7)
      thor (>= 0.18.1, < 2.0)
    rake (10.1.0)
    rdoc (3.12.2)
      json (~> 1.4)
    sass (3.2.9)
    sass-rails (4.0.0)
      railties (>= 4.0.0.beta, < 5.0)
      sass (>= 3.1.10)
      sprockets-rails (~> 2.0.0)
    sdoc (0.3.20)
      json (>= 1.1.3)
      rdoc (~> 3.10)
    sprockets (2.10.0)
      hike (~> 1.2)
      multi_json (~> 1.0)
      rack (~> 1.0)
      tilt (~> 1.1, != 1.3.0)
    sprockets-rails (2.0.0)
      actionpack (>= 3.0)
      activesupport (>= 3.0)
      sprockets (~> 2.8)
    sqlite3 (1.3.7)
    thor (0.18.1)
    thread_safe (0.1.0)
      atomic
    tilt (1.4.1)
    treetop (1.4.14)
      polyglot
      polyglot (>= 0.3.1)
    turbolinks (1.3.0)
      coffee-rails
    tzinfo (0.3.37)
    uglifier (2.1.2)
      execjs (>= 0.3.0)
      multi_json (~> 1.0, >= 1.0.2)

PLATFORMS
  ruby

DEPENDENCIES
  coffee-rails (~> 4.0.0)
  jbuilder (~> 1.2)
  jquery-rails
  rails (= 4.0.0)
  sass-rails (~> 4.0.0)
  sdoc
  sqlite3
  turbolinks
  uglifier (>= 1.3.0)
The advantage of Gemfile.lock is that it makes it possible for several developers to work on the same Rails project independently from one another and to still be sure that they are all working with the same gem versions. If a file is Gemfile.lock, this will be used by the Bundler. This is also useful for deploying the Rails project later on a web server.
Thanks to this mechanism you can use and develop several Rails projects with different gem version numbers in parallel.

bundle update

With bundle update you can update gems to new versions. As an example, I have a Rails project with the Rails version 4.0.0:
$ rails -v
Rails 4.0.0
$
In the file Gemfile, this version is listed:
$ head -n 4 Gemfile
source 'https://rubygems.org'

# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
gem 'rails', '4.0.0'
$ 
And also in the Gemfile.lock:
$ grep 'rails' Gemfile.lock 
    coffee-rails (4.0.0)
    jquery-rails (3.0.4)
    rails (4.0.0)
      sprockets-rails (~> 2.0.0)
    sass-rails (4.0.0)
      sprockets-rails (~> 2.0.0)
    sprockets-rails (2.0.0)
      coffee-rails
  coffee-rails (~> 4.0.0)
  jquery-rails
  rails (= 4.0.0)
  sass-rails (~> 4.0.0)
$
If we want to update this Rails project to the Rails version 4.0.1, we need to change the entry in the Gemfile as follows:
source 'https://rubygems.org'

# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
gem 'rails', '4.0.1'

# Use sqlite3 as the database for Active Record
gem 'sqlite3'

# Use SCSS for stylesheets
gem 'sass-rails', '~> 4.0.0'

# Use Uglifier as compressor for JavaScript assets
gem 'uglifier', '>= 1.3.0'

# Use CoffeeScript for .js.coffee assets and views
gem 'coffee-rails', '~> 4.0.0'

# See https://github.com/sstephenson/execjs#readme for more supported runtimes
# gem 'therubyracer', platforms: :ruby

# Use jquery as the JavaScript library
gem 'jquery-rails'

# Turbolinks makes following links in your web application faster. Read more: https://github.com/rails/turbolinks
gem 'turbolinks'

# Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder
gem 'jbuilder', '~> 1.2'

group :doc do
  # bundle exec rake doc:rails generates the API under doc/api.
  gem 'sdoc', require: false
end

# Use ActiveModel has_secure_password
# gem 'bcrypt-ruby', '~> 3.0.0'

# Use unicorn as the app server
# gem 'unicorn'

# Use Capistrano for deployment
# gem 'capistrano', group: :development

# Use debugger
# gem 'debugger', group: [:development, :test]
After this change, you can use bundle update rails to install the new Rails version (required dependencies are automatically taken into account by Bundler):
$ bundle update rails
  [...]
$ rails -v
Rails 4.0.1
$

Buy the new Rails 5.1 version of this book.

After every gem update, you should first run rake test to make sure that a new gem version does not add any unwanted side effects.

bundle outdated

If you want to know which of the gems used by your Rails project are now available in a new version, you can do this via the command bundle outdated. Example:
$ bundle outdated
Fetching gem metadata from https://rubygems.org/..........
Fetching gem metadata from https://rubygems.org/..
Resolving dependencies...

Outdated gems included in the bundle:
  * builder (3.2.2 > 3.1.4)
  * minitest (5.0.6 > 4.7.5)
  * rdoc (4.0.1 > 3.12.2)
  * tzinfo (1.0.1 > 0.3.37)
$

bundle exec

bundle exec is probably one of the commands Rails developers hate the most. It is required whenever a program such as rake is used in a Rails project and is present in a different version than the rest of the system. The resulting error message is always easy to implement:
You have already activated rake 0.10, but your Gemfile requires rake 0.9.2.2. Using bundle exec may solve this.
In this case, it helps to invoke the command with a preceding bundle exec:
$ bundle exec rake db:migrate

binstubs

In some environments, using bundle exec is too complicated. In that case, you can install programs with the correct version via bundle install --binstubs in the directory bin:
$ bundle install --binstubs
Using rake (10.1.0) 
Using i18n (0.6.4) 
Using minitest (4.7.5) 
Using multi_json (1.7.7) 
Using atomic (1.1.10) 
Using thread_safe (0.1.0) 
Using tzinfo (0.3.37) 
Using activesupport (4.0.0) 
Using builder (3.1.4) 
Using erubis (2.7.0) 
Using rack (1.5.2) 
Using rack-test (0.6.2) 
Using actionpack (4.0.0) 
Using mime-types (1.23) 
Using polyglot (0.3.3) 
Using treetop (1.4.14) 
Using mail (2.5.4) 
Using actionmailer (4.0.0) 
Using activemodel (4.0.0) 
Using activerecord-deprecated_finders (1.0.3) 
Using arel (4.0.0) 
Using activerecord (4.0.0) 
Using coffee-script-source (1.6.3) 
Using execjs (1.4.0) 
Using coffee-script (2.2.0) 
Using thor (0.18.1) 
Using railties (4.0.0) 
Using coffee-rails (4.0.0) 
Using hike (1.2.3) 
Using jbuilder (1.4.2) 
Using jquery-rails (3.0.4) 
Using json (1.8.0) 
Using bundler (1.3.5) 
Using tilt (1.4.1) 
Using sprockets (2.10.0) 
Using sprockets-rails (2.0.0) 
Using rails (4.0.0) 
Using rdoc (3.12.2) 
Using sass (3.2.9) 
Using sass-rails (4.0.0) 
Using sdoc (0.3.20) 
Using sqlite3 (1.3.7) 
Using turbolinks (1.3.0) 
Using uglifier (2.1.2) 
Your bundle is complete!
Use `bundle show [gemname]` to see where a bundled gem is installed.
SW:webshop stefan$ ls bin
bundle  rake  sass-convert  sprockets
erubis  rdoc  scss          thor
rackup  ri    sdoc          tilt
rails   sass  sdoc-merge    tt
$
Afterwards, you can always use these programs. Example:
$ bin/rake db:migrate
==  CreateUsers: migrating ====================================================
-- create_table(:users)
   -> 0.0018s
==  CreateUsers: migrated (0.0019s) ===========================================

$

Further Information on Bundler

The topic Bundler is far more complex than can be described here. If you want to find out more on Bundler, please visit the following websites to find further information:

Thank you for your support and the visibility by linking to this website on Twitter and Facebook. That helps a lot!