Add bundle update and bundle package

2 files changed, 229 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.
diff --git a/man/bundle-update.ronn b/man/bundle-update.ronn
new file mode 100644
index 0000000000..5e66c45b80
--- /dev/null
+++ b/man/bundle-update.ronn
@@ -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