forked from rubygems/bundler-site
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
bundle update and bundle package
- Loading branch information
Showing
2 changed files
with
229 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Original file line | Diff line number | Diff line change |
---|---|---|---|
@@ -0,0 +1,53 @@ | |||
bundle-package(1) -- Package your needed `.gem` files into your application | |||
=========================================================================== | |||
|
|||
## SYNOPSIS | |||
|
|||
`bundle package` | |||
|
|||
## DESCRIPTION | |||
|
|||
Copy all of the `.gem` files needed to run the application into the | |||
`vendor/cache` directory. In the future, when running `bundle install(1)`, | |||
use the gems in the cache in preference to the ones on `rubygems.org`. | |||
|
|||
## REMOTE FETCHING | |||
|
|||
By default, if you simply run `bundle install(1)` after running | |||
`bundle package(1)`, bundler will still connect to `rubygems.org` | |||
to check whether a platform-specific gem exists for any of the gems | |||
in `vendor/cache`. | |||
|
|||
For instance, consider this `Gemfile(7)`: | |||
|
|||
source "http://rubygems.org" | |||
|
|||
gem "nokogiri" | |||
|
|||
If you run `bundle package` under C Ruby, bundler will retrieve | |||
the version of `nokogiri` for the `"ruby"` platform. If you deploy | |||
to JRuby and run `bundle install`, bundler is forced to check to | |||
see whether a `"java"` platformed `nokogiri` exists. | |||
|
|||
Even though the `nokogiri` gem for the Ruby platform is | |||
_technically_ acceptable on JRuby, it actually has a C extension | |||
that does not run on JRuby. As a result, bundler will, by default, | |||
still connect to `rubygems.org` to check whether it has a version | |||
of one of your gems more specific to your platform. | |||
|
|||
This problem is also not just limited to the `"java"` platform. | |||
A similar (common) problem can happen when developing on Windows | |||
and deploying to Linux, or even when developing on OSX and | |||
deploying to Linux. | |||
|
|||
If you know for sure that the gems packaged in `vendor/cache` | |||
are appropriate for the platform you are on, you can run | |||
`bundle install --local` to skip checking for more appropriate | |||
gems, and just use the ones in `vendor/cache`. | |||
|
|||
One way to be sure that you have the right platformed versions | |||
of all your gems is to run `bundle package` on an identical | |||
machine and check in the gems. For instance, you can run | |||
`bundle package` on an identical staging box during your | |||
staging process, and check in the `vendor/cache` before | |||
deploying to production. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Original file line | Diff line number | Diff line change |
---|---|---|---|
@@ -0,0 +1,176 @@ | |||
bundle-update(1) -- Update your gems to the latest available versions | |||
===================================================================== | |||
|
|||
## SYNOPSIS | |||
|
|||
`bundle update` <*gems> [--source=NAME] | |||
|
|||
## DESCRIPTION | |||
|
|||
Update the gems specified (all gems, if none are specified), ignoring | |||
the previously installed gems specified in the `Gemfile.lock`. In | |||
general, you should use `bundle install(1)` to install the same exact | |||
gems and versions across machines. | |||
|
|||
You would use `bundle update` to explicitly update the version of a | |||
gem. | |||
|
|||
## OPTIONS | |||
|
|||
* `--source=<name>`: | |||
The name of a `:git` or `:path` source used in the `Gemfile`. For | |||
instance, with a `:git` source of `http://github.com/rails/rails.git`, | |||
you would call `bundle update --source rails` | |||
|
|||
## UPDATING ALL GEMS | |||
|
|||
If you run `bundle update` with no parameters, bundler will ignore | |||
any previously installed gems and resolve all dependencies again | |||
based on the latest versions of all gems available in the sources. | |||
|
|||
Consider the following `Gemfile`: | |||
|
|||
source "http://rubygems.org" | |||
|
|||
gem "rails", "3.0.0.rc" | |||
gem "nokogiri" | |||
|
|||
When you run `bundle install(1)` the first time, bundler will resolve | |||
all of the dependencies, all the way down, and install what you need: | |||
|
|||
Fetching source index for http://rubygems.org/ | |||
Installing rake (0.8.7) | |||
Installing abstract (1.0.0) | |||
Installing activesupport (3.0.0.rc) | |||
Installing builder (2.1.2) | |||
Installing i18n (0.4.1) | |||
Installing activemodel (3.0.0.rc) | |||
Installing erubis (2.6.6) | |||
Installing rack (1.2.1) | |||
Installing rack-mount (0.6.9) | |||
Installing rack-test (0.5.4) | |||
Installing tzinfo (0.3.22) | |||
Installing actionpack (3.0.0.rc) | |||
Installing mime-types (1.16) | |||
Installing polyglot (0.3.1) | |||
Installing treetop (1.4.8) | |||
Installing mail (2.2.5) | |||
Installing actionmailer (3.0.0.rc) | |||
Installing arel (0.4.0) | |||
Installing activerecord (3.0.0.rc) | |||
Installing activeresource (3.0.0.rc) | |||
Installing bundler (1.0.0.rc.3) | |||
Installing nokogiri (1.4.3.1) with native extensions | |||
Installing thor (0.14.0) | |||
Installing railties (3.0.0.rc) | |||
Installing rails (3.0.0.rc) | |||
|
|||
Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed. | |||
|
|||
As you can see, even though you have just two gems in the `Gemfile(7)`, your application | |||
actually needs 25 different gems in order to run. Bundler remembers the exact versions | |||
it installed in `Gemfile.lock`. The next time you run `bundle install(1)`, bundler skips | |||
the dependency resolution and installs the same gems as it installed last time. | |||
|
|||
After checking in the `Gemfile.lock` into version control and cloning it on another | |||
machine, running `bundle install(1)` will _still_ install the gems that you installed | |||
last time. You don't need to worry that a new release of `erubis` or `mail` changes | |||
the gems you use. | |||
|
|||
However, from time to time, you might want to update the gems you are using to the | |||
newest versions that still match the gems in your `Gemfile(7)`. | |||
|
|||
To do this, run `bundle update`, which will ignore the `Gemfile.lock`, and resolve | |||
all the dependencies again. Keep in mind that this process can result in a significantly | |||
different set of the 25 gems, based on the requirements of new gems that the gem | |||
authors released since the last time you ran `bundle update`. | |||
|
|||
## UPDATING A LIST OF GEMS | |||
|
|||
Sometimes, you want to update a single gem in the `Gemfile(7)`, and leave the rest of the | |||
gems that you specified locked to the versions in the `Gemfile.lock`. | |||
|
|||
For instance, in the scenario above, imagine that `nokogiri` releases version `1.4.4`, and | |||
you want to update it _without_ updating Rails and all of its dependencies. To do this, | |||
run `bundle update nokogiri`. | |||
|
|||
Bundler will update `nokogiri` and any of its dependencies, but leave alone Rails and | |||
its dependencies. | |||
|
|||
## OVERLAPPING DEPENDENCIES | |||
|
|||
Sometimes, multiple gems declared in your `Gemfile(1)` are satisfied by the same | |||
second-level dependency. For instance, consider the case of `thin` and | |||
`rack-perftools-profiler`. | |||
|
|||
source "http://rubygems.org" | |||
|
|||
gem "thin" | |||
gem "rack-perftools-profiler" | |||
|
|||
The `thin` gem depends on `rack >= 1.0`, while `rack-perftools-profiler` depends | |||
on `rack ~> 1.0`. If you run bundle install, you get: | |||
|
|||
Fetching source index for http://rubygems.org/ | |||
Installing daemons (1.1.0) | |||
Installing eventmachine (0.12.10) with native extensions | |||
Installing open4 (1.0.1) | |||
Installing perftools.rb (0.4.7) with native extensions | |||
Installing rack (1.2.1) | |||
Installing rack-perftools_profiler (0.0.2) | |||
Installing thin (1.2.7) with native extensions | |||
Using bundler (1.0.0.rc.3) | |||
|
|||
In this case, the two gems have their own set of dependencies, but they share | |||
`rack` in common. If you run `bundle update thin`, bundler will update `daemons`, | |||
`eventmachine` and `rack`, which are dependencies of `thin`, but not `open4` or | |||
`perftools.rb`, which are dependencies of `rack-perftools_profiler`. Note that | |||
`bundle update thin` will update `rack` even though it's _also_ a dependency of | |||
`rack-perftools_profiler`. | |||
|
|||
`In short`, when you update a gem using `bundle update`, bundler will update all | |||
dependencies of that gem, including those that are also dependencies of another gem. | |||
|
|||
In this scenario, updating the `thin` version manually in the `Gemfile(7)`, | |||
and then running `bundle install(1)` will only update `daemons` and `eventmachine`, | |||
but not `rack`. For more information, see the `CONSERVATIVE UPDATING` section | |||
of `bundle install(1)`. | |||
|
|||
## RECOMMENDED WORKFLOW | |||
|
|||
In general, when working with an application managed with bundler, you should | |||
use the following workflow: | |||
|
|||
* After you create your `Gemfile` for the first time, run | |||
|
|||
$ bundle install | |||
|
|||
* Check the resulting `Gemfile.lock` into version control | |||
|
|||
$ git add Gemfile.lock | |||
|
|||
* When checking out this repository on another development machine, run | |||
|
|||
$ bundle install | |||
|
|||
* When checking out this repository on a deployment machine, run | |||
|
|||
$ bundle install --deployment | |||
|
|||
* After changing the `Gemfile(7)` to reflect a new or update dependency, run | |||
|
|||
$ bundle install | |||
|
|||
* Make sure to check the updated `Gemfile.lock` into version control | |||
|
|||
$ git add Gemfile.lock | |||
|
|||
* If `bundle install(1)` reports a conflict, manually update the specific | |||
gems that you changed in the `Gemfile(7)` | |||
|
|||
$ bundle update rails thin | |||
|
|||
* If you want to update all the gems to the latest possible versions that | |||
still match the gems listed in the `Gemfile(7)`, run | |||
|
|||
$ bundle update |