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:
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:
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:
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:
As you work in the application, you may wish to add dependencies. To do so, update the Gemfile, and run:
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:
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 install in the future, Bundler will use packed gems, if available, in preference to gems available in other sources.
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.