New bundle update options documented.

Fixes #4775.

2 files changed, 156 insertions, 6 deletions

diff --git a/lib/bundler/cli.rb b/lib/bundler/cli.rb
index 37556f4926..8e8f13701b 100644
--- a/lib/bundler/cli.rb
+++ b/lib/bundler/cli.rb
@@ -222,9 +222,9 @@ module Bundler
     method_option "major", :type => :boolean, :banner =>
       "Prefer updating to next major version (default)"
     method_option "strict", :type => :boolean, :banner =>
-      "Do not allow any gem to be updated past latest --patch/--minor/--major"
+      "Do not allow any gem to be updated past latest --patch | --minor | --major"
     method_option "conservative", :type => :boolean, :banner =>
-      "Use bundle install conservative update behavior and do not allowed shared dependencies to be updated."
+      "Use bundle install conservative update behavior and do not allow shared dependencies to be updated."
     def update(*gems)
       require "bundler/cli/update"
       Update.new(options, gems).run
@@ -478,7 +478,7 @@ module Bundler
     method_option "strict", :type => :boolean, :banner =>
       "If updating, do not allow any gem to be updated past latest --patch | --minor | --major"
     method_option "conservative", :type => :boolean, :banner =>
-      "If updating, use bundle install conservative update behavior and do not allowed shared dependencies to be updated."
+      "If updating, use bundle install conservative update behavior and do not allow shared dependencies to be updated."
     def lock
       require "bundler/cli/lock"
       Lock.new(options).run
diff --git a/man/bundle-update.ronn b/man/bundle-update.ronn
index 47d70f661c..1083c9db41 100644
--- a/man/bundle-update.ronn
+++ b/man/bundle-update.ronn
@@ -3,7 +3,18 @@ bundle-update(1) -- Update your gems to the latest available versions
 
 ## SYNOPSIS
 
-`bundle update` <*gems> [--group=NAME] [--source=NAME] [--local] [--ruby]
+`bundle update` <*gems> [--group=NAME]
+                        [--source=NAME]
+                        [--local]
+                        [--ruby]
+                        [--bundler[=VERSION]]
+                        [--full-index]
+                        [--jobs=JOBS]
+                        [--quiet]
+                        [--force]
+                        [--patch|--minor|--major]
+                        [--strict]
+                        [--conservative]
 
 ## DESCRIPTION
 
@@ -37,6 +48,34 @@ gem.
 * `--bundler`:
   Update the locked version of bundler to the invoked bundler version.
 
+* `--full-index`:
+  Fall back to using the single-file index of all gems.
+
+* `--jobs`:
+  Specify the number of jobs to run in parallel.
+
+* `--quiet`:
+  Only output warnings and errors.
+
+* `--force`:
+  Force downloading every gem.
+
+* `--patch`:
+  Prefer updating only to next patch version.
+
+* `--minor`:
+  Prefer updating only to next minor version.
+
+* `--major`:
+  Prefer updating to next major version (default).
+
+* `--strict`:
+  Do not allow any gem to be updated past latest `--patch` | `--minor` | `--major`.
+
+* `--conservative`:
+  Use bundle install conservative update behavior and do not allow shared dependencies to be updated.
+
+
 ## UPDATING ALL GEMS
 
 If you run `bundle update` with no parameters, bundler will ignore
@@ -146,14 +185,125 @@ In this case, the two gems have their own set of dependencies, but they share
 `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 short, by default, 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.
+
+To prevent updating shared dependencies, prior to version 1.14 the only option
+was the `CONSERVATIVE UPDATING` behavior in [bundle install(1)][bundle-install]:
 
 In this scenario, updating the `thin` version manually in the Gemfile(5),
 and then running [bundle install(1)][bundle-install] will only update `daemons` and `eventmachine`,
 but not `rack`. For more information, see the `CONSERVATIVE UPDATING` section
 of [bundle install(1)][bundle-install].
 
+Starting with 1.14, specifying the `--conservative` option will also prevent shared
+dependencies from being updated.
+
+## PATCH LEVEL OPTIONS
+
+Version 1.14 introduced 4 patch-level options that will influence how gem
+versions are resolved. One of the following options can be used: `--patch`,
+`--minor` or `--major`. `--strict` can be added to further influence resolution.
+
+* `--patch`:
+  Prefer updating only to next patch version.
+
+* `--minor`:
+  Prefer updating only to next minor version.
+
+* `--major`:
+  Prefer updating to next major version (default).
+
+* `--strict`:
+  Do not allow any gem to be updated past latest `--patch` | `--minor` | `--major`.
+
+When Bundler is resolving what versions to use to satisfy declared
+requirements in the Gemfile or in parent gems, it looks up all
+available versions, filters out any versions that don't satisfy
+the requirement, and then, by default, sorts them from newest to
+oldest, considering them in that order.
+
+Providing one of the patch level options (e.g. `--patch`) changes the
+sort order of the satisfying versions, causing Bundler to consider the
+latest `--patch` or `--minor` version available before other versions.
+Note that versions outside the stated patch level could still be
+resolved to if necessary to find a suitable dependency graph.
+
+For example, if gem 'foo' is locked at 1.0.2, with no gem requirement
+defined in the Gemfile, and versions 1.0.3, 1.0.4, 1.1.0, 1.1.1, 2.0.0
+all exist, the default order of preference by default (`--major`) will
+be "2.0.0, 1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2".
+
+If the `--patch` option is used, the order of preference will change to
+"1.0.4, 1.0.3, 1.0.2, 1.1.1, 1.1.0, 2.0.0".
+
+If the `--minor` option is used, the order of preference will change to
+"1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2, 2.0.0".
+
+Combining the `--strict` option with any of the patch level options
+will remove any versions beyond the scope of the patch level option,
+to ensure that no gem is updated that far.
+
+To continue the previous example, if both `--patch` and `--strict`
+options are used, the available versions for resolution would be
+"1.0.4, 1.0.3, 1.0.2". If `--minor` and `--strict` are used, it would
+be "1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2".
+
+Gem requirements as defined in the Gemfile will still be the first
+determining factor for what versions are available. If the gem
+requirement for `foo` in the Gemfile is '~> 1.0', that will accomplish
+the same thing as providing the `--minor` and `--strict` options.
+
+## PATCH LEVEL EXAMPLES
+
+Given the following gem specifications:
+
+    foo 1.4.3, requires: ~> bar 2.0
+    foo 1.4.4, requires: ~> bar 2.0
+    foo 1.4.5, requires: ~> bar 2.1
+    foo 1.5.0, requires: ~> bar 2.1
+    foo 1.5.1, requires: ~> bar 3.0
+    bar with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1, 3.0.0
+    
+Gemfile:
+
+    gem 'foo'
+ 
+Gemfile.lock:
+
+    foo (1.4.3)
+      bar (~> 2.0)
+    bar (2.0.3)
+                                  
+Cases:
+
+    #  Command Line                     Result
+    ------------------------------------------------------------
+    1  bundle update --patch            'foo 1.4.5', 'bar 2.1.1'
+    2  bundle update --patch foo        'foo 1.4.5', 'bar 2.1.1'
+    3  bundle update --minor            'foo 1.5.1', 'bar 3.0.0'
+    4  bundle update --minor --strict   'foo 1.5.0', 'bar 2.1.1'
+    5  bundle update --patch --strict   'foo 1.4.4', 'bar 2.0.4'
+       
+In case 1, bar is upgraded to 2.1.1, a minor version increase, because
+the dependency from foo 1.4.5 required it.
+
+In case 2, only foo is requested to be unlocked, but bar is also
+allowed to move because it's not a declared dependency in the Gemfile.
+
+In case 3, bar goes up a whole major release, because a minor increase
+is preferred now for foo, and when it goes to 1.5.1, it requires 3.0.0
+of bar.
+
+In case 4, foo is preferred up to a minor version, but 1.5.1 won't work
+because the --strict flag removes bar 3.0.0 from consideration since
+it's a major increment.
+
+In case 5, both foo and bar have any minor or major increments removed
+from consideration because of the --strict flag, so the most they can
+move is up to 1.4.4 and 2.0.4.
+
 ## RECOMMENDED WORKFLOW
 
 In general, when working with an application managed with bundler, you should