Taking into consideration the huge amount of feedback we received during the Bundler 0.9 series, we streamlined Bundler 1.0 significantly, and made it fit user expectations better.
Whether you have used bundler before or not, the easiest way to get up to speed is to read the following notes and go to http://gembundler.com/v1.0 for more in-depth information.
(note that gembundler.com is still being updated for the 1.0 changes, and should be ready for the final release).
Starting a new project with bundler
When you generate a new Rails application, Rails will create a
Gemfile for you, which has everything needed to boot your application.
Otherwise, you can use
bundle init to create a stub
Gemfile, ready to go.
bundle install to make sure that you have all the needed dependencies. If you already do, this process will happen instantaneously.
Bundler will automatically create a file called
Gemfile.lock. This file is a snapshot of your application's dependencies at that time.
You SHOULD check both files into version control. This will ensure that all team members (as well as your production server) are working with identical dependencies.
Checking out an existing project using bundler
After checking out an existing project using bundler, check to make sure that the
Gemfile.lock snapshot is checked in. If it is not, you may end up using different dependencies than the person who last used and tested the project.
bundle install. This command will check whether you already have all the required dependencies in your system. If you do not, it will fetch the dependencies and install them.
If you modify the dependencies in your
Gemfile, first try to run
bundle install, as usual. Bundler will attempt to update only the gems you have modified, leaving the rest of the snapshot intact.
This may not be possible, if the changes conflict with other gems in the snapshot (or their dependencies). If this happens, Bundler will instruct you to run
bundle update. This will re-resolve all dependencies from scratch.
bundle update command will update the versions of all gems in your
bundle install will only update the gems that have changed since the last
After modifying dependencies, make sure to check in your
Gemfile.lock into version control.
By default, gems are installed to your system
If you follow the instructions above, Bundler will install the gems into the same place as
If necessary, Bundler will prompt you for your
You can see the location of a particular gem with
bundle show [GEM_NAME]. You can open it in your default editor with
bundle open [GEM_NAME].
Bundler will still isolate your application from other gems. Installing your gems into a shared location allows multiple projects to avoid downloading the same gem over and over.
You might want to install your bundled gems to a different location, such as a directory in the application itself. This will ensure that each application has its own copies of the gems, and provides an extra level of isolation.
To do this, run the install command with
bundle install /path/to/location. You can use a relative path as well:
bundle install vendor.
In RC1, this command will use gems from the system, if they are already there (it only affects new gems). To ensure that all of your gems are located in the path you specified, run
bundle install path --disable-shared-gems.
In Bundler 1.0 final,
bundle install path will default to
When deploying, we strongly recommend that you isolate your gems into a local path (using
bundle install path --disable-shared-gems). The final version of bundler will come with a
--production flag, encapsulating all of the best deployment practices.
For now, please follow the following recommendations (described using Capistrano concepts):
- Make sure to always check in a
Gemfile.lockthat is up to date. This means that after modifying your
Gemfile, you should ALWAYS run
- Symlink the vendor/bundle directory into the application's shared location (symlink release_path/current/vendor/bundle to release_path/shared/bundled_gems)
- Install your bundle by running
bundle install vendor/bundle --disable-shared-gems