This article was written for Bundler version 1.0. If you are using a later version of Bundler, the commands and code here may or may not work. If in doubt refer to the Bundler home page.

Considering Bundler does a relatively complex job, the basics of using Bundler to manage gem dependencies in your projects is very simple. In a nutshell, you'll be editing a file that describes what gems your project depends on and slightly modifying how you require those gems.

Installing Bundler

If you haven't already, install Bundler. It's a simple gem, installed from the Rubygems repository. No surprises here.

$ gem install bundler
Also, make sure you have the bundlecommand line program in your path. If you have Rubygems set up correctly, this should be working for you.

$ bundle --versionBundler version 1.0.22

Generating a Gemfile

Go to your project directory on the command line. If you haven't already started a project, start one now and generate whatever files you need to if you're using a project generator (like the Rails project generator). Once you're in the new directory, run the bundle init command. This will create your Gemfile file. This is, for the most part, where all your Bundler stuff goes.

~$ cd awesomeproject/awesomeproject$ lsREADME lib/ main.rbawesomeproject$ bundle initWriting new Gemfile to /Users/user/awesomeproject/Gemfileawesomeproject$ lsGemfileREADME lib/ main.rb

Defining Dependencies

You're all ready to start defining dependencies.

Each dependency you define in your Gemfile should be a gem your project directly relies on. For example, if your project uses the Chronic gem, you should list it in this file. The gems you should not list are dependencies of your dependencies. Those will be taken care of in a separate step. So, just to repeat, only dependencies your project directly relies on. Pretty much only the gems you require directly.

Here is the example Gemfile generated by bundler init. It lists a gem repository (the official Rubygems repository, it's possible to list your own here) and an example (and commented out) dependency. Also note that this is not a special file. It's just a Ruby file, you can (and will) do a bit more than a simple list of gems here.

# A sample Gemfilesource "http://rubygems.org"# gem "rails"
Since out imaginary project relies on the Chronic gem as well as the graph gem, we'll list those in this file. Note that there are no version numbers listed yet.

# Gemfile for an awesome projectsource "http://rubygems.org"gem 'chronic'gem 'graph'

Defining Versions

If necessary, you can define versions for your dependencies. For example, if I know my project needs version 2.5.0 of the graph gem, no earlier version will do, I should explicitly state that here. Similarly, if you want the exact version of a gem installed (if, for example, you rely on some unexpected behavior not present in other versions), you may also want to define this here. Defining gem versions is done with a small string with some familiar operators (and one slightly complicated one).

• "= 2.5.0" - The project requires version 2.5.0, and no other version.
• "!= 2.5.0" - Or the project requires any version except 2.5.0, maybe that version is very broken?
• "> 2.5.0" - Anything greater than 2.5.0 will do.
• " - Or less than 2.5.0.
• ">= 2.5.0" or " - Greater/less than or equal to 2.5.0.
• "~> 2.5" - Approximately greater than. This takes advantage of the rational versioning policy. Saying "~> 2.5" is the equivalent of saying "anything 2.5 or greater, but less than 3." It does this by dropping the last digit (in this case, 5) and incrementing the next digit. So, we could have also said "~> 2.5.0" which would mean something slightly different. Drop the last digit and increment the next to the last and we get "anything greater than 2.5.0 or less than 2.6.0." This is possibly the most used operator here, so get to know it.

So, in our example project I know that I need the 2.5.0 version of the graph gem, but I want to make sure I stay in the 2.5.x branch, so I'll define the version as "~> 2.5.0".

# A sample Gemfilesource "http://rubygems.org"gem 'chronic'gem 'graph', "~> 2.5.0"

Locking In

Once you have the direct dependencies listed, it's time to install your dependencies and make your Gemfile.lock file. This lock file is very important, it will list the required version of every gem required by your project. Not only the the depencies you listed, but the gems those depend on. This is a very important file for application developers. This is the file that bundle install uses to make sure the correct gem version for every gem is installed. Having a predictable environment with predictable gem version is very desirable for application developers. So make sure you check this file into version control so other developers have the same set of gem versions.

So, to install the gems and create this file, run the command bundle install.

$ bundle installUsing chronic (0.6.7) Using graph (2.5.0) Using bundler (1.0.22) Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.$ cat Gemfile.lockGEMremote: http://rubygems.org/specs:chronic (0.6.7)graph (2.5.0)PLATFORMSrubyDEPENDENCIESchronicgraph (~> 2.5.0)

Require the Right Gem

By default, Rubygems will require the latest version of a gem. In order to prevent this from happening in your project, you need to add another require after Rubygems but before any of your gems. This will read your Gemfile and make sure Rubygems grabs the correct version, even if a newer version is installed.

require "rubygems"require "bundler/setup"require "chronic"require "graph"