Add bundle update and bundle package

1 files changed, 53 insertions, 0 deletions

diff --git a/man/bundle-package.ronn b/man/bundle-package.ronn
new file mode 100644
index 0000000000..8fe1732bbf
--- /dev/null
+++ b/man/bundle-package.ronn
@@ -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.