diff options
Diffstat (limited to 'man/bundle-update.1.txt')
| -rw-r--r-- | man/bundle-update.1.txt | 390 |
1 files changed, 390 insertions, 0 deletions
diff --git a/man/bundle-update.1.txt b/man/bundle-update.1.txt new file mode 100644 index 0000000000..d2ec46444b --- /dev/null +++ b/man/bundle-update.1.txt @@ -0,0 +1,390 @@ +BUNDLE-UPDATE(1) BUNDLE-UPDATE(1) + + + +1mNAME0m + 1mbundle-update 22m- Update your gems to the latest available versions + +1mSYNOPSIS0m + 1mbundle update 4m22m*gems24m [--all] [--group=NAME] [--source=NAME] [--local] + [--ruby] [--bundler[=VERSION]] [--full-index] [--jobs=JOBS] [--quiet] + [--patch|--minor|--major] [--redownload] [--strict] [--conservative] + +1mDESCRIPTION0m + Update the gems specified (all gems, if 1m--all 22mflag is used), ignoring + the previously installed gems specified in the 1mGemfile.lock22m. In gen- + eral, you should use bundle install(1) 4mbundle-install.1.html24m to install + the same exact gems and versions across machines. + + You would use 1mbundle update 22mto explicitly update the version of a gem. + +1mOPTIONS0m + 1m--all 22mUpdate all gems specified in Gemfile. + + 1m--group=<name>22m, 1m-g=[<name>]0m + Only update the gems in the specified group. For instance, you + can update all gems in the development group with 1mbundle update0m + 1m--group development22m. You can also call 1mbundle update rails0m + 1m--group test 22mto update the rails gem and all gems in the test + group, for example. + + 1m--source=<name>0m + The name of a 1m:git 22mor 1m:path 22msource used in the Gemfile(5). For + instance, with a 1m:git 22msource of + 1mhttp://github.com/rails/rails.git22m, you would call 1mbundle update0m + 1m--source rails0m + + 1m--local0m + Do not attempt to fetch gems remotely and use the gem cache + instead. + + 1m--ruby 22mUpdate the locked version of Ruby to the current version of + Ruby. + + 1m--bundler0m + Update the locked version of bundler to the invoked bundler ver- + sion. + + 1m--full-index0m + Fall back to using the single-file index of all gems. + + 1m--jobs=[<number>]22m, 1m-j[<number>]0m + Specify the number of jobs to run in parallel. The default is 1m122m. + + 1m--retry=[<number>]0m + Retry failed network or git requests for 4mnumber24m times. + + 1m--quiet0m + Only output warnings and errors. + + 1m--redownload0m + Force downloading every gem. + + 1m--patch0m + Prefer updating only to next patch version. + + 1m--minor0m + Prefer updating only to next minor version. + + 1m--major0m + Prefer updating to next major version (default). + + 1m--strict0m + Do not allow any gem to be updated past latest 1m--patch 22m| 1m--minor0m + | 1m--major22m. + + 1m--conservative0m + Use bundle install conservative update behavior and do not allow + shared dependencies to be updated. + +1mUPDATING ALL GEMS0m + If you run 1mbundle update --all22m, 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(5): + + + + source "https://rubygems.org" + + gem "rails", "3.0.0.rc" + gem "nokogiri" + + + + When you run bundle install(1) 4mbundle-install.1.html24m the first time, + bundler will resolve all of the dependencies, all the way down, and + install what you need: + + + + Fetching gem metadata from https://rubygems.org/......... + Resolving dependencies... + Installing builder 2.1.2 + Installing abstract 1.0.0 + Installing rack 1.2.8 + Using bundler 1.7.6 + Installing rake 10.4.0 + Installing polyglot 0.3.5 + Installing mime-types 1.25.1 + Installing i18n 0.4.2 + Installing mini_portile 0.6.1 + Installing tzinfo 0.3.42 + Installing rack-mount 0.6.14 + Installing rack-test 0.5.7 + Installing treetop 1.4.15 + Installing thor 0.14.6 + Installing activesupport 3.0.0.rc + Installing erubis 2.6.6 + Installing activemodel 3.0.0.rc + Installing arel 0.4.0 + Installing mail 2.2.20 + Installing activeresource 3.0.0.rc + Installing actionpack 3.0.0.rc + Installing activerecord 3.0.0.rc + Installing actionmailer 3.0.0.rc + Installing railties 3.0.0.rc + Installing rails 3.0.0.rc + Installing nokogiri 1.6.5 + + Bundle complete! 2 Gemfile dependencies, 26 gems total. + Use `bundle show [gemname]` to see where a bundled gem is installed. + + + + As you can see, even though you have two gems in the Gemfile(5), your + application needs 26 different gems in order to run. Bundler remembers + the exact versions it installed in 1mGemfile.lock22m. The next time you run + bundle install(1) 4mbundle-install.1.html24m, bundler skips the dependency + resolution and installs the same gems as it installed last time. + + After checking in the 1mGemfile.lock 22minto version control and cloning it + on another machine, running bundle install(1) 4mbundle-install.1.html0m + will 4mstill24m install the gems that you installed last time. You don't + need to worry that a new release of 1merubis 22mor 1mmail 22mchanges 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 Gem- + file(5). + + To do this, run 1mbundle update --all22m, which will ignore the 1mGem-0m + 1mfile.lock22m, 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 1mbundle update --all22m. + +1mUPDATING A LIST OF GEMS0m + Sometimes, you want to update a single gem in the Gemfile(5), and leave + the rest of the gems that you specified locked to the versions in the + 1mGemfile.lock22m. + + For instance, in the scenario above, imagine that 1mnokogiri 22mreleases + version 1m1.4.422m, and you want to update it 4mwithout24m updating Rails and all + of its dependencies. To do this, run 1mbundle update nokogiri22m. + + Bundler will update 1mnokogiri 22mand any of its dependencies, but leave + alone Rails and its dependencies. + +1mOVERLAPPING DEPENDENCIES0m + Sometimes, multiple gems declared in your Gemfile(5) are satisfied by + the same second-level dependency. For instance, consider the case of + 1mthin 22mand 1mrack-perftools-profiler22m. + + + + source "https://rubygems.org" + + gem "thin" + gem "rack-perftools-profiler" + + + + The 1mthin 22mgem depends on 1mrack >= 1.022m, while 1mrack-perftools-profiler0m + depends on 1mrack ~> 1.022m. If you run bundle install, you get: + + + + Fetching source index for https://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 1mrack 22min common. If you run 1mbundle update thin22m, bundler will + update 1mdaemons22m, 1meventmachine 22mand 1mrack22m, which are dependencies of 1mthin22m, + but not 1mopen4 22mor 1mperftools.rb22m, which are dependencies of + 1mrack-perftools_profiler22m. Note that 1mbundle update thin 22mwill update 1mrack0m + even though it's 4malso24m a dependency of 1mrack-perftools_profiler22m. + + In short, by default, when you update a gem using 1mbundle update22m, + 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 1mCONSERVATIVE UPDATING 22mbehavior in bundle install(1) 4mbun-0m + 4mdle-install.1.html24m: + + In this scenario, updating the 1mthin 22mversion manually in the Gemfile(5), + and then running bundle install(1) 4mbundle-install.1.html24m will only + update 1mdaemons 22mand 1meventmachine22m, but not 1mrack22m. For more information, + see the 1mCONSERVATIVE UPDATING 22msection of bundle install(1) 4mbun-0m + 4mdle-install.1.html24m. + + Starting with 1.14, specifying the 1m--conservative 22moption will also pre- + vent shared dependencies from being updated. + +1mPATCH LEVEL OPTIONS0m + Version 1.14 introduced 4 patch-level options that will influence how + gem versions are resolved. One of the following options can be used: + 1m--patch22m, 1m--minor 22mor 1m--major22m. 1m--strict 22mcan be added to further influence + resolution. + + 1m--patch0m + Prefer updating only to next patch version. + + 1m--minor0m + Prefer updating only to next minor version. + + 1m--major0m + Prefer updating to next major version (default). + + 1m--strict0m + Do not allow any gem to be updated past latest 1m--patch 22m| 1m--minor0m + | 1m--major22m. + + When Bundler is resolving what versions to use to satisfy declared + requirements in the Gemfile or in parent gems, it looks up all avail- + able versions, filters out any versions that don't satisfy the require- + ment, and then, by default, sorts them from newest to oldest, consider- + ing them in that order. + + Providing one of the patch level options (e.g. 1m--patch22m) changes the + sort order of the satisfying versions, causing Bundler to consider the + latest 1m--patch 22mor 1m--minor 22mversion 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 (1m--major22m) will be + "2.0.0, 1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2". + + If the 1m--patch 22moption 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 1m--minor 22moption 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 1m--strict 22moption 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 1m--patch 22mand 1m--strict 22moptions + are used, the available versions for resolution would be "1.0.4, 1.0.3, + 1.0.2". If 1m--minor 22mand 1m--strict 22mare 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 require- + ment for 1mfoo 22min the Gemfile is '~> 1.0', that will accomplish the same + thing as providing the 1m--minor 22mand 1m--strict 22moptions. + +1mPATCH LEVEL EXAMPLES0m + 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. + +1mRECOMMENDED WORKFLOW0m + In general, when working with an application managed with bundler, you + should use the following workflow: + + o After you create your Gemfile(5) for the first time, run + + $ bundle install + + o Check the resulting 1mGemfile.lock 22minto version control + + $ git add Gemfile.lock + + o When checking out this repository on another development machine, + run + + $ bundle install + + o When checking out this repository on a deployment machine, run + + $ bundle install --deployment + + o After changing the Gemfile(5) to reflect a new or update depen- + dency, run + + $ bundle install + + o Make sure to check the updated 1mGemfile.lock 22minto version control + + $ git add Gemfile.lock + + o If bundle install(1) 4mbundle-install.1.html24m reports a conflict, man- + ually update the specific gems that you changed in the Gemfile(5) + + $ bundle update rails thin + + o If you want to update all the gems to the latest possible versions + that still match the gems listed in the Gemfile(5), run + + $ bundle update --all + + + + + + + October 2018 BUNDLE-UPDATE(1) |