If you'd like a full description, read at the very least the "Understanding Bundler" section of http://gembundler.com
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
.
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.
@indirect, thanks for the advice. I've updated the document. I think I'll save the version specifiers for a different writeup.