Bundler for the TL;DR impaired

bundler_tldr.markdown

Bundler for the TL;DR impaired

If you'd like a full description, read at the very least the "Understanding Bundler" section of http://gembundler.com

Commands

bundle install - This command is your meat-and-potatoes-everyday command, use this to get the gems and dependencies installed that are listed in your Gemfile.lock.

bundle update - this is a once in awhile DEVELOPER ONLY command that is used to consciously and intentionally update the Gemfile.lock to contain newer versions of all the gems. bundle update <gemname> is preferred, as it will only update the versions of <gemname> and dependencies of <gemname>. The non-specific bundle update command is similar to deleting Gemfile.lock and running bundle install.

How do we work with bundler? A simple example:

Lets say you are starting a new project, and you need to use the rdoc gem, so you make a Gemfile:

source :rubygems
gem 'rdoc'

This Gemfile says that you want to use the latest version of the rdoc gem. You then run bundle install. Bundler connects to rubygems.org and determines that the latest version of the rdoc gem is 3.12 and that it depends on the json gem at or above version 1.4 (using the ~> operator). It downloads the rdoc gem at the latest version, and it downloads the json gem at version 1.7.1 (the current latest that is on rubygems for 1.x and greater or equal to 1.4). Bundler then writes a Gemfile.lock file that looks something like this:

GEM
  remote: http://rubygems.org/
  specs:
    json (1.7.1)
    rdoc (3.12)
      json (~> 1.4)

PLATFORMS
  ruby

DEPENDENCIES
  rdoc

This specifies that the rdoc 3.12 gem is to be installed and the json 1.7.1 gem is to be installed.

Later, you bring Bob in on the project and he sets up his development environment. Bob gets the code (you do use a SCM, right?) and runs bundle install. At this point, Bundler checks the Gemfile and Gemfile.lock to ensure that the Gemfile hasn't changed, and then using the Gemfile.lock as a guide, downloads and installs rdoc 3.12 and json 1.7.1.

Now, imagine some time later, a new version of json comes out, say 2.0.0, and also during that time, a couple of fixes have been made to the json 1.x branch and a new 1.7.3 gem has been released. Now, if you run bundle install with the current set of Gemfile and Gemfile.lock, you will continue to get rdoc 3.12 and json 1.7.1 each time. Bob sees that there are fixes to the json gem that solve some problems he was having. Bob then runs bundle update json in his development environment. Bundler uses the current Gemfile.lock as a guide and does the discovery and install again for the json gem, this time picking up json 1.7.3 because it fits the ~> spec (the major version is 1, and the minor version is 4 or greater) and writing an updated Gemfile.lock.

Bundler didn't pick up the json 2.0.0 gem because it didn't match the ~> spec. It also didn't pick up any new versions of rdoc because there aren't any.

Later, Bob decides to add a Rakefile to the project, so he also adds rake (with no version requirements) to the Gemfile. Running bundle install this time causes the Gemfile.lock to be rewritten again, but regardless of new gems for json or rdoc, those will remain in the Gemfile.lock as they are.

Stay tuned for my next discussion, Deploying with Bundler for the TL;DR impaired.

I'd suggest using the full bundle install rather than just bundle. people get confused that their bundle installs instead of printing a help message, so we'll probably require an explicit install in 2.0.

In general, I'd suggest explaining the way that version specifiers work using the Gemfile, and not discussing the contents of the lock. You shouldn't ever need to open or edit the lock file, so all this talk about the contents of the lock worries me a bit. Maybe you can just talk about how the lock records the exact versions, and the lock is how other installs.

bundle update doesn't delete the lockfile. It tries to use the lockfile as the basis for a new resolve, upgrading as many versions as it can while still coming up with a clean resolve. bundle update json is even more conservative, and only updates versions of the json gem and any gems the json gem depends on. bundle install is (as you wrote) the most conservative of them all, and will never update versions itself -- it will only add gems, remove gems, and change versions exactly following version specifier changes in the Gemfile.

HTH.

@indirect, thanks for the advice. I've updated the document. I think I'll save the version specifiers for a different writeup.