Whether you need a specific gem and version, or a set of gems for a certain environment; Bundler is a fantastic tool for managing your applications dependencies.
Gemfiles are the source of your bundle, used by bundler to determine what gems to install and require in different situations. It's important to understand the difference between the Gemfile and Gemfile.lock; Gemfiles are where you specify the actual gems required by your application, and the Gemfile.lock is a definition of all the required gems and the exact versions used by your application. As it's necessary for other developers to know exactly what versions of third party libraries you're using, the Gemfile.lock is recommended to be checked into source control.
In most cases you're going to require gems from the official rubygems repository. Here's an example Gemfile for an application that uses Sinatra as a main dependency and RSpec for testing:
# define our source to loook for gems source "http://rubygems.org/" # declare the sinatra dependency gem "sinatra" # setup our test group and require rspec group :test do gem "rspec" end # require a relative gem version gem "i18n", "~> 0.4.1"
Bundler also supports the installation of gems through git, so long as the repository contains a valid gemspec for the gem you're trying to install.
# lets use sinatra edge gem "sinatra", :git => "http://github.com/sinatra/sinatra.git" # and lets we use the rspec 2.0 release candidate from git group :test do gem "rspec", :git => "http://github.com/rspec/rspec.git", :tag => "v2.0.0.rc" end # as well as i18n from git gem "i18n", :git => "http://github.com/svenfuchs/i18n.git"
Bundle is the command line utility provided with Bundler to install, update and manage your bundle. Here's a quick overview of some of the most common commands.
# Install specified gems from your Gemfile and Gemfile.lock bundle install
# Inspect your bundle to see if you've met your applications requirements bundle check
# List all gems in your bundle bundle list
# Show source location of a specific gem in your bundle bundle show [gemname]
# Generate a skeleton Gemfile to start your path to using Bundler bundle init
Updating your bundle will look in the given repositories for the latest versions available. This will bypass your Gemfile.lock and check for completely new versions. Alternatively you can specify an individual gem to update, and bundler will only update that gem to the latest version available in the specified repository.
# Update all gems specified to the latest versions available bundle update
# Update just i18n to the latest gem version available bundle update i18n
Bundler provides two main ways to use your bundle in your application,
Setup basically tells Ruby all of your gems loadpaths, and
require will load all of your specified gems.
bundler/setup is the same as calling
Bundler.setup yourself, and is the recommended method in the
# If you're using Ruby 1.9 you'll need to specifically load rubygems require 'rubygems' # and now load bundler with your dependencies load paths require 'bundler/setup' # next you'll have to do the gem requiring yourself require 'sinatra' require 'i18n'
Now if say you skip the last step, and just auto require gems from your groups
require 'rubygems' require 'bundler/setup' # this will require all the gems not specified to a given group (default) # and gems specified in your test group Bundler.require(:default, :test)
Bundler’s Purpose and Rationale - For a longer explanation of what Bundler does and how it works
CLI Manual - Basic command line utilities provided with Bundler
Gems from Git repositories - Using git repositories with your Gemfile
Using Groups - Using groups with bundler