What does Rails 3's Bundler "bundle install --deployment" exactly do?

Question

The things described in the formal documentation are a bit complicated.

Does it merely add the following line to .bundle/config

BUNDLE_PATH: vendor/bundle

and then perform a bundle install, and that's it? (install will then install all the gems into vendor/bundle)

Then when the application runs, it will look for the gems in this path specified in .bundle/config, and that's it?

Update: if I use Mercurial (similar to Git) to keep track of files in project, then after doing the bundle install --deployment, the only changes are a lot of files added to vendor/bundle, and 2 lines added to .bundle/config:

BUNDLE_FROZEN: "1"
BUNDLE_PATH: vendor/bundle

Answer 1

bundle install --deployment does indeed install the gems locally to the vendor/bundle directory in the application. This is reflected by the config change in the path setting which you mentioned (BUNDLE_PATH: vendor/bundle). This approach is known as "freezing" or "vendoring" the gems and it forces the application to use the locally installed gems, rather than the global system gems,which is convenient default for deployment. As mentioned in bundler documentation:

"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."