318 lines
12 KiB
Markdown
318 lines
12 KiB
Markdown
bundle-install(1) -- Install the dependencies specified in your Gemfile
|
|
=======================================================================
|
|
|
|
## SYNOPSIS
|
|
|
|
`bundle install` [--gemfile=GEMFILE]
|
|
[--path PATH] [--system]
|
|
[--without=GROUP1[ GROUP2...]]
|
|
[--local] [--deployment]
|
|
[--binstubs[=DIRECTORY]]
|
|
[--quiet]
|
|
|
|
## DESCRIPTION
|
|
|
|
Install the gems specified in your Gemfile(5). If this is the first
|
|
time you run bundle install (and a `Gemfile.lock` does not exist),
|
|
bundler will fetch all remote sources, resolve dependencies and
|
|
install all needed gems.
|
|
|
|
If a `Gemfile.lock` does exist, and you have not updated your Gemfile(5),
|
|
bundler will fetch all remote sources, but use the dependencies
|
|
specified in the `Gemfile.lock` instead of resolving dependencies.
|
|
|
|
If a `Gemfile.lock` does exist, and you have updated your Gemfile(5),
|
|
bundler will use the dependencies in the `Gemfile.lock` for all gems
|
|
that you did not update, but will re-resolve the dependencies of
|
|
gems that you did update. You can find more information about this
|
|
update process below under [CONSERVATIVE UPDATING][].
|
|
|
|
## OPTIONS
|
|
|
|
* `--gemfile=<gemfile>`:
|
|
The location of the Gemfile(5) that bundler should use. This defaults
|
|
to a gemfile in the current working directory. In general, bundler
|
|
will assume that the location of the Gemfile(5) is also the project
|
|
root, and will look for the `Gemfile.lock` and `vendor/cache` relative
|
|
to it.
|
|
|
|
* `--path=<path>`:
|
|
The location to install the gems in the bundle to. This defaults
|
|
to the gem home, which is the location that `gem install` installs
|
|
gems to. This means that, by default, gems installed without a
|
|
`--path` setting will show up in `gem list`. This setting is a
|
|
[remembered option][REMEMBERED OPTIONS].
|
|
|
|
* `--system`:
|
|
Installs the gems in the bundle to the system location. This
|
|
overrides any previous [remembered][REMEMBERED OPTIONS] use of
|
|
`--path`.
|
|
|
|
* `--without=<list>`:
|
|
A space-separated list of groups to skip installing. This is a
|
|
[remembered option][REMEMBERED OPTIONS].
|
|
|
|
* `--local`:
|
|
Do not attempt to connect to `rubygems.org`, instead using just
|
|
the gems located in `vendor/cache`. Note that if a more
|
|
appropriate platform-specific gem exists on `rubygems.org`,
|
|
this will bypass the normal lookup.
|
|
|
|
* `--deployment`:
|
|
Switches bundler's defaults into [deployment mode][DEPLOYMENT MODE].
|
|
Do not use this flag on development machines.
|
|
|
|
* `--binstubs[=<directory>]`:
|
|
Create a directory (defaults to `bin`) containing an executable
|
|
that runs in the context of the bundle. For instance, if the
|
|
`rails` gem comes with a `rails` executable, this flag will create
|
|
a `bin/rails` executable that ensures that all dependencies used
|
|
come from the bundled gems.
|
|
|
|
## DEPLOYMENT MODE
|
|
|
|
Bundler's defaults are optimized for development. To switch to
|
|
defaults optimized for deployment, use the `--deployment` flag.
|
|
Do not activate deployment mode on development machines, as it
|
|
will cause in an error when the Gemfile is modified.
|
|
|
|
1. A `Gemfile.lock` is required.
|
|
|
|
To ensure that the same versions of the gems you developed with
|
|
and tested with are also used in deployments, a `Gemfile.lock`
|
|
is required.
|
|
|
|
This is mainly to ensure that you remember to check your
|
|
`Gemfile.lock` into version control.
|
|
|
|
2. The `Gemfile.lock` must be up to date
|
|
|
|
In development, you can modify your Gemfile(5) and re-run
|
|
`bundle install` to [conservatively update][CONSERVATIVE UPDATING]
|
|
your `Gemfile.lock` snapshot.
|
|
|
|
In deployment, your `Gemfile.lock` should be up-to-date with
|
|
changes made in your Gemfile(5).
|
|
|
|
3. Gems are installed to `vendor/bundle` not your default system location
|
|
|
|
In development, it's convenient to share the gems used in your
|
|
application with other applications and other scripts run on
|
|
the system.
|
|
|
|
In deployment, isolation is a more important default. In addition,
|
|
the user deploying the application may not have permission to install
|
|
gems to the system, or the web server may not have permission to
|
|
read them.
|
|
|
|
As a result, `bundle install --deployment` installs gems to
|
|
the `vendor/bundle` directory in the application. This may be
|
|
overridden using the `--path` option.
|
|
|
|
## SUDO USAGE
|
|
|
|
By default, bundler installs gems to the same location as `gem install`.
|
|
|
|
In some cases, that location may not be writable by your Unix user. In
|
|
that case, bundler will stage everything in a temporary directory,
|
|
then ask you for your `sudo` password in order to copy the gems into
|
|
their system location.
|
|
|
|
From your perspective, this is identical to installing them gems
|
|
directly into the system.
|
|
|
|
You should never use `sudo bundle install`. This is because several
|
|
other steps in `bundle install` must be performed as the current user:
|
|
|
|
* Updating your `Gemfile.lock`
|
|
* Updating your `vendor/cache`, if necessary
|
|
* Checking out private git repositories using your user's SSH keys
|
|
|
|
Of these three, the first two could theoretically be performed by
|
|
`chown`ing the resulting files to `$SUDO_USER`. The third, however,
|
|
can only be performed by actually invoking the `git` command as
|
|
the current user. Therefore, git gems are downloaded and installed
|
|
into `~/.bundle` rather than $GEM_HOME or $BUNDLE_PATH.
|
|
|
|
As a result, you should run `bundle install` as the current user,
|
|
and bundler will ask for your password if it is needed to put the
|
|
gems into their final location.
|
|
|
|
## INSTALLING GROUPS
|
|
|
|
By default, `bundle install` will install all gems in all groups
|
|
in your Gemfile(5), except those declared for a different platform.
|
|
|
|
However, you can explicitly tell bundler to skip installing
|
|
certain groups with the `--without` option. This option takes
|
|
a space-separated list of groups.
|
|
|
|
While the `--without` option will skip _installing_ the gems in the
|
|
specified groups, it will still _download_ those gems and use them to
|
|
resolve the dependencies of every gem in your Gemfile(5).
|
|
|
|
This is so that installing a different set of groups on another
|
|
machine (such as a production server) will not change the
|
|
gems and versions that you have already developed and tested against.
|
|
|
|
`Bundler offers a rock-solid guarantee that the third-party
|
|
code you are running in development and testing is also the
|
|
third-party code you are running in production. You can choose
|
|
to exclude some of that code in different environments, but you
|
|
will never be caught flat-footed by different versions of
|
|
third-party code being used in different environments.`
|
|
|
|
For a simple illustration, consider the following Gemfile(5):
|
|
|
|
source "http://rubygems.org"
|
|
|
|
gem "sinatra"
|
|
|
|
group :production do
|
|
gem "rack-perftools-profiler"
|
|
end
|
|
|
|
In this case, `sinatra` depends on any version of Rack (`>= 1.0`, while
|
|
`rack-perftools-profiler` depends on 1.x (`~> 1.0`).
|
|
|
|
When you run `bundle install --without production` in development, we
|
|
look at the dependencies of `rack-perftools-profiler` as well. That way,
|
|
you do not spend all your time developing against Rack 2.0, using new
|
|
APIs unavailable in Rack 1.x, only to have bundler switch to Rack 1.2
|
|
when the `production` group _is_ used.
|
|
|
|
This should not cause any problems in practice, because we do not
|
|
attempt to `install` the gems in the excluded groups, and only evaluate
|
|
as part of the dependency resolution process.
|
|
|
|
This also means that you cannot include different versions of the same
|
|
gem in different groups, because doing so would result in different
|
|
sets of dependencies used in development and production. Because of
|
|
the vagaries of the dependency resolution process, this usually
|
|
affects more than just the gems you list in your Gemfile(5), and can
|
|
(surprisingly) radically change the gems you are using.
|
|
|
|
## REMEMBERED OPTIONS
|
|
|
|
Some options (marked above in the [OPTIONS][] section) are remembered
|
|
between calls to `bundle install`, and by the Bundler runtime.
|
|
|
|
For instance, if you run `bundle install --without test`, a subsequent
|
|
call to `bundle install` that does not include a `--without` flag will
|
|
remember your previous choice.
|
|
|
|
In addition, a call to `Bundler.setup` will not attempt to make the
|
|
gems in those groups available on the Ruby load path, as they were
|
|
not installed.
|
|
|
|
The settings that are remembered are:
|
|
|
|
* `--deployment`:
|
|
At runtime, this remembered setting will also result in Bundler
|
|
raising an exception if the `Gemfile.lock` is out of date.
|
|
|
|
* `--path`:
|
|
Subsequent calls to `bundle install` will install gems to the
|
|
directory originally passed to `--path`. The Bundler runtime
|
|
will look for gems in that location. You can revert this
|
|
option by running `bundle install --system`.
|
|
|
|
* `--binstubs`:
|
|
Bundler will update the executables every subsequent call to
|
|
`bundle install`.
|
|
|
|
* `--without`:
|
|
As described above, Bundler will skip the gems specified by
|
|
`--without` in subsequent calls to `bundle install`. The
|
|
Bundler runtime will also not try to make the gems in the
|
|
skipped groups available.
|
|
|
|
## THE GEMFILE.LOCK
|
|
|
|
When you run `bundle install`, Bundler will persist the full names
|
|
and versions of all gems that you used (including dependencies of
|
|
the gems specified in the Gemfile(5)) into a file called `Gemfile.lock`.
|
|
|
|
Bundler uses this file in all subsequent calls to `bundle install`,
|
|
which guarantees that you always use the same exact code, even
|
|
as your application moves across machines.
|
|
|
|
Because of the way dependency resolution works, even a
|
|
seemingly small change (for instance, an update to a point-release
|
|
of a dependency of a gem in your Gemfile(5)) can result in radically
|
|
different gems being needed to satisfy all dependencies.
|
|
|
|
As a result, you `SHOULD` check your `Gemfile.lock` into version
|
|
control. If you do not, every machine that checks out your
|
|
repository (including your production server) will resolve all
|
|
dependencies again, which will result in different versions of
|
|
third-party code being used if `any` of the gems in the Gemfile(5)
|
|
or any of their dependencies have been updated.
|
|
|
|
## CONSERVATIVE UPDATING
|
|
|
|
When you make a change to the Gemfile(5) and then run `bundle install`,
|
|
Bundler will update only the gems that you modified.
|
|
|
|
In other words, if a gem that you `did not modify` worked before
|
|
you called `bundle install`, it will continue to use the exact
|
|
same versions of all dependencies as it used before the update.
|
|
|
|
Let's take a look at an example. Here's your original Gemfile(5):
|
|
|
|
source "http://rubygems.org"
|
|
|
|
gem "actionpack", "2.3.8"
|
|
gem "activemerchant"
|
|
|
|
In this case, both `actionpack` and `activemerchant` depend on
|
|
`activesupport`. The `actionpack` gem depends on `activesupport 2.3.8`
|
|
and `rack ~> 1.1.0`, while the `activemerchant` gem depends on
|
|
`activesupport >= 2.3.2`, `braintree >= 2.0.0`, and `builder >= 2.0.0`.
|
|
|
|
When the dependencies are first resolved, Bundler will select
|
|
`activesupport 2.3.8`, which satisfies the requirements of both
|
|
gems in your Gemfile(5).
|
|
|
|
Next, you modify your Gemfile(5) to:
|
|
|
|
source "http://rubygems.org"
|
|
|
|
gem "actionpack", "3.0.0.rc"
|
|
gem "activemerchant"
|
|
|
|
The `actionpack 3.0.0.rc` gem has a number of new dependencies,
|
|
and updates the `activesupport` dependency to `= 3.0.0.rc` and
|
|
the `rack` dependency to `~> 1.2.1`.
|
|
|
|
When you run `bundle install`, Bundler notices that you changed
|
|
the `actionpack` gem, but not the `activemerchant` gem. It
|
|
evaluates the gems currently being used to satisfy its requirements:
|
|
|
|
* `activesupport 2.3.8`:
|
|
also used to satisfy a dependency in `activemerchant`,
|
|
which is not being updated
|
|
* `rack ~> 1.1.0`:
|
|
not currently being used to satify another dependency
|
|
|
|
Because you did not explicitly ask to update `activemerchant`,
|
|
you would not expect it to suddenly stop working after updating
|
|
`actionpack`. However, satisfying the new `activesupport 3.0.0.rc`
|
|
dependency of actionpack requires updating one of its dependencies.
|
|
|
|
Even though `activemerchant` declares a very loose dependency
|
|
that theoretically matches `activesupport 3.0.0.rc`, bundler treats
|
|
gems in your Gemfile(5) that have not changed as an atomic unit
|
|
together with their dependencies. In this case, the `activemerchant`
|
|
dependency is treated as `activemerchant 1.7.1 + activesupport 2.3.8`,
|
|
so `bundle install` will report that it cannot update `actionpack`.
|
|
|
|
To explicitly update `actionpack`, including its dependencies
|
|
which other gems in the Gemfile(5) still depend on, run
|
|
`bundle update actionpack` (see `bundle update(1)`).
|
|
|
|
`Summary`: In general, after making a change to the Gemfile(5) , you
|
|
should first try to run `bundle install`, which will guarantee that no
|
|
other gems in the Gemfile(5) are impacted by the change. If that
|
|
does not work, run [bundle update(1)][bundle-update].
|