Bundler Reference

Kip Landergren

April 16, 2019 (Updated: December 04, 2023)

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

Bundler Terminology
Commands
Examples
FAQ
Resources
bundler-study
- Gemfile
- README.md

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:

increment the version number (e.g. 0.0.1 to 0.0.2)
remove the gem from the Gemfile, run bundle install, then add it back

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

rubygems/rubygems GitHub repository, where bundler is maintained
Bundler documentation

bundler-study

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

README.md

# bundler-study

Personal study area for [Bundler](https://bundler.io)

Bundler Reference

Contents