Using Bundler in Real Life

A lot of people have asked me what the recommended workflows for bundler are. Turns out, they're quite simple.

Let's step through a few use-cases.

You Get a Repo for the First Time

You've just checked out a git (or other) repository for an application that uses bundler. Regardless of any other features of bundler in use, just run:

bundle install

This will resolve all dependencies and install the ones that aren't already installed in system gems or in your system's bundler cache.

You Update a Repo Using Bundler

If you update a repository using bundler, and it has updated its dependencies in the Gemfile, regardless of any other features in use, just run:

bundle install

As above, this will resolve all dependencies and install any gems that are not already installed.

You have created a new Rails application

If you've created a new Rails application, go inside it and run:

bundle install

This will make sure that Rails' dependencies (such as SQLite3) are available in system gems or your system's bundler cache. In most cases, this will not need to install anything.

To check whether your system already satisfied the application's dependencies, run:

bundle check

As you work in the application, you may wish to add dependencies. To do so, update the Gemfile, and run:

bundle install

You are ready to share your new Rails application

Now that you have a working Rails application, and wish to share, you might wish to ensure that your collaborators get the same versions of the gems as you have. For instance, if webrat specified "nokogiri >= 1.4" as a dependency, you might want to ensure that an update to nokogiri does not change the actual gems that bundle install will install.

To achieve this, run:

bundle lock

This will create a new file called Gemfile.lock in your root directory that contains the dependencies that you specified, as well as the fully resolved dependency graph. Check that file into source control.

When your collaborators receive the repository and run bundle install, bundler will use the resolved dependencies in Gemfile.lock.

You have a locked application, and wish to add a new dependency

If you add a new dependency to your Gemfile in a locked application, Bundler will give you an error if you try to perform any operations.

You will want to run bundle unlock to remove the lock, then bundle install to ensure that the new dependencies are installed on your system, and finally bundle lock again to relock your application to the new dependencies.

We will add a command in a near-future version to perform all these steps for you (something like bundle install --relock).

You want a self-contained application

In many cases, it is desirable to be able to have a self-contained application that you can share with others which contains all of the required gems.

In addition to a general desire to remove a dependency on Gemcutter, you might have dependencies on gems that are not on a publicly accessible gem repository.

To collect up all gems and place them into your app, run:

bundle pack

When running bundle install in the future, Bundler will use packed gems, if available, in preference to gems available in other sources.

Conclusion

I hope these workflows have clarified the intent of Bundler 0.9 (and 1.0). During our work on earlier versions, the lack of these workflows came up again and again as a source of frustration. This was the primary reason for the big changes in 0.9, so I hope you find them useful.