diff options
author | chrismo <chrismo@clabs.org> | 2016-10-22 00:37:30 -0500 |
---|---|---|
committer | chrismo <chrismo@clabs.org> | 2016-10-22 23:48:22 -0500 |
commit | 2e61117454ff3ef7f614ad003a87fcbafa975978 (patch) | |
tree | 32abef44d03f5a54b2847aab3e356575af45b465 /man | |
parent | ff068ade5ce9728bc0c2525fb47ca2d443168998 (diff) | |
download | bundler-2e61117454ff3ef7f614ad003a87fcbafa975978.tar.gz |
New bundle update options documented.
Fixes #4775.
Diffstat (limited to 'man')
-rw-r--r-- | man/bundle-update.ronn | 156 |
1 files changed, 153 insertions, 3 deletions
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 |