Recommended Workflow with Version Control

A Thorough Bundler Workflow

Getting started with bundler is easy! Open a terminal window and run this command:
$ gem install bundler
  • When you first create a Rails application, it already comes with a Gemfile. For another kind of application (such as Sinatra), run:
    $ bundle init
  • The bundle init command creates a simple Gemfile which you can edit.
  • Specify your dependencies in the root of your application, called the Gemfile. It looks something like this:
    source ''
    gem 'nokogiri'
    gem 'rack', '~> 2.0.1'
    gem 'rspec'
    This Gemfile says a few things. First, it says that bundler should look for gems declared in the Gemfile at by default.
    Learn More: Gemfiles

    After declaring your first set of dependencies, you tell bundler to go get them:

    $ bundle install    # <code>bundle</code> is a shortcut for <code>bundle install</code>

    Bundler will connect to (and any other sources that you declared), and find a list of all of the required gems that meet the requirements you specified. Because all of the gems in your Gemfile have dependencies of their own (and some of those have their own dependencies), running bundle install on the Gemfile above will install quite a few gems.

      $ bundle install
      Fetching gem metadata from
      Fetching version metadata from
      Fetching dependency metadata from
      Resolving dependencies...
      Installing rake 11.3.0
      Using concurrent-ruby 1.0.2
      Using i18n 0.7.0
      Installing minitest 5.9.1
      Using thread_safe 0.3.5
      Using builder 3.2.2
      Using erubis 2.7.0
      Using mini_portile2 2.1.0
      Using rack 2.0.1
      Using nio4r 1.2.1
      Using websocket-extensions 0.1.2
      Installing mime-types-data 3.2016.0521
      Installing arel 7.1.4
      Using bundler 1.13.1
      Using method_source 0.8.2
      Using thor 0.19.1
      Using tzinfo 1.2.2
      Installing nokogiri with native extensions
      Using rack-test 0.6.3
      Using sprockets 3.7.0
      Installing websocket-driver 0.6.4 with native extensions
      Installing mime-types 3.1
      Using activesupport
      Using loofah 2.0.3
      Using mail 2.6.4
      Using rails-dom-testing 2.0.1
      Using globalid 0.3.7
      Using activemodel
      Using rails-html-sanitizer 1.0.3
      Using activejob
      Using activerecord
      Using actionview
      Using actionpack
      Using actioncable
      Using actionmailer
      Using railties
      Installing sprockets-rails 3.2.0
      Using rails
      Bundle complete! 1 Gemfile dependency, 38 gems now installed.
      Use `bundle show [gemname]` to see where a bundled gem is installed.

    If any of the needed gems are already installed, Bundler will use them. After installing any needed gems to your system, bundler writes a snapshot of all of the gems and versions that it installed to Gemfile.lock.

  • If bundle install reports a conflict between your Gemfile and Gemfile.lock, run:
    $ bundle update sinatra
  • This will update just the Sinatra gem, as well as any of its dependencies.
  • To update all of the gems in your Gemfile to the latest possible versions, run:
    $ bundle update
  • Whenever your Gemfile.lock changes, always check it in to version control. It keeps a history of the exact versions of all third-party code that you used to successfully run your application.
  • The git add Gemfile* command adds the Gemfile and Gemfile.lock to your repository. This ensures that other developers on your app, as well as your deployment environment, will all use the same third-party code that you are using now.
  • Inside your app, load up the bundled environment:
    require 'rubygems'
    require 'bundler/setup'
    # require your gems as usual
    require 'nokogiri'
    Learn More: Bundler.setup
    Run an executable that comes with a gem in your bundle:
    $ bundle exec rspec spec/models

    In some cases, running executables without bundle exec may work, if the executable happens to be installed in your system and does not pull in any gems that conflict with your bundle.

    However, this is unreliable and is the source of considerable pain. Even if it looks like it works, it may not work in the future or on another machine.

    Finally, if you want a way to get a shortcut to gems in your bundle:
    $ bundle install --binstubs
    $ bin/rspec spec/models
    The executables installed into bin are scoped to the bundle, and will always work.
    Learn More: Executables
    Edit this document on GitHub if you caught an error or noticed something was missing.