Bundler Reference

Kip Landergren

(Updated: )

My cheat sheet for Bundler covering Gemfile usage, terminology, and frequently used commands.

Contents

Bundler Terminology

bundle
the collection of gems specified by Gemfile.lock

Commands

IMPORTANT: is the environment variable BUNDLE_IGNORE_CONFIG set correctly? This controls whether bundler’s configuration (not the Gemfile) is read.
bundle exec [command] execute command in context of bundle
bundle config list print list of bundler configuration for the current bundle
bundle info [GEM] show information for [GEM]
bundle list list all gems in the bundle
bundle list --paths list all gems in the bundle, with paths
bundle update [GEM] attempts to update [GEM]; leaving off [GEM] attempts to update entire Gemfile

Examples

Start irb using the bundler-managed gems:

$ bundle exec irb

FAQ

How to develop a gem locally and get bundler to pull in changes?

Two options before running bundle install or bundle update:

More info in this StackOverflow question How to force the update of a gem with bundler?.

How to get bundler to use a local built .gem?

I have not found out how yet, but I think it involves adding the .gem file to a local index. Best work around so far is to specify the local directory. This has drawbacks of not being the exact .gem shipped to RubyGems or your gem server.

I have tried unpacking a built .gem to a directory and using bundler’s path: specification but got errors about it not being able to find any gem.

How to update a specific gem within the Gemfile?

$ bundle update [GEM]

How to update bundler itself? How to update the bundler version in Gemfile.lock?

Tell bundler to upgrade itself:

$ bundle update --bundler

Why does the documentation refer to Gemfile(5)? What does the “(5)” mean in Gemfile(5)?

It is a reference to the man page section. From the output of man man:

MANUAL SECTIONS
The standard sections of the manual include:

  1 User Commands
  2 System Calls
  3 C Library Functions
  4 Devices and Special Files
  5 File Formats and Conventions
  6 Games et. Al.
  7 Miscellanea
  8 System Administration tools and Deamons

Distributions customize the manual section to their specifics, which often include additional sections.

Resources

Example Gemfile

source "https://rubygems.org"

# == gem and version specifications ==

gem "rack"                 # latest version (at time of fresh install)
gem "typhoeus", "1.4.0"    # exact version
gem "thor", "< 1.3.0"      # the latest version (at time of fresh install) of the 1.2.x releases
gem "rails", ">= 6.1.0"    # the latest version (at time of fresh install) greater than or equal to 6.1.0
gem "nokogiri", "~> 1.9.0" # equivalent to: gem "nokogiri", ">= 1.9.0", "< 1.10.0"

gem "jekyll-last-commit", path: "~/Projects/jekyll-last-commit"         # specify a local path
gem 'jekyll', git: 'https://github.com/jekyll/jekyll', branch: 'master' # specify a remote repo and branch

# note: the `~>` operator works based on the *specificity* of the version. If
# we instead used "~> 1.9" then all versions 1.x greater than or equal to 1.9
# and less than 2.0 are valid

# == groups ==
#
# `group` allows for actions to be performed on the entire group. these actions
# are facilitated by bundler—external libraries can make use of them. some use
# cases include:
#
#  - installing specific gems on a per-environment basis
#
#  - indicating to a framework that specific gems should be treated differently
#    (e.g. group :jekyll_plugins for Jekyll)
group :development do
  gem "rspec"
end