Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, June 13, 2019

bundle-update (1)


bundle-update - Man page for 'bundle-update' in section 1


Please see following description for synopsis


TH "BUNDLE-UPDATE" "1" "December 2018" "" "" SH "NAME" bundle-up-
date - Update your gems to the latest available versions SH "SYN-
OPSIS" bundle update *gems [--all] [--group=NAME] [--source=NAME]
[--local]    [--ruby]    [--bundler[=VERSION]]     [--full-index]
[--jobs=JOBS]   [--quiet]   [--force]   [--patch|--minor|--major]
[--strict] [--conservative]  SH  "DESCRIPTION"  Update  the  gems
specified  (all gems, if --all flag is used), ignoring the previ-
ously installed gems specified in the Gemfile.lock.  In  general,
you should use bundle install(1) bundle-install.1.html to install
the same exact gems and versions across machines.   P  You  would
use  bundle update to explicitly update the version of a gem.  SH
"OPTIONS" TP --all Update all  gems  specified  in  Gemfile.   TP
--group=<name>, -g=[<name>] Only update the gems in the specified
group. For instance, you can update all gems in  the  development
group  with  bundle update --group development. You can also call
bundle update rails --group test to update the rails gem and  all
gems in the test group, for example.  TP --source=<name> The name
of a :git or :path source used in the Gemfile(5).  For  instance,
with  a  :git  source  of  http://github.com/rails/rails.git, you
would call bundle update --source rails TP --local Do not attempt
to  fetch gems remotely and use the gem cache instead.  TP --ruby
Update the locked version of Ruby to the current version of Ruby.
TP  --bundler Update the locked version of bundler to the invoked
bundler version.  TP --full-index Fall back  to  using  the  sin-
gle-file  index  of all gems.  TP --jobs=[<number>], -j[<number>]
Specify the number of jobs to run in parallel. The default is  1.
TP  --retry=[<number>]  Retry  failed network or git requests for
number times.  TP --quiet Only output warnings  and  errors.   TP
--force  Force downloading every gem. --redownload is an alias of
this option.  TP --patch Prefer updating only to next patch  ver-
sion.  TP --minor Prefer updating only to next minor version.  TP
--major Prefer updating to  next  major  version  (default).   TP
--strict Do not allow any gem to be updated past latest --patch |
--minor | --major.  TP --conservative Use bundle install  conser-
vative update behavior and do not allow shared dependencies to be
updated.  SH "UPDATING ALL GEMS" If you run bundle update  --all,
bundler will ignore any previously installed gems and resolve all
dependencies again based on  the  latest  versions  of  all  gems
available  in  the sources.  P Consider the following Gemfile(5):
IP "" 4 nf

source "https://rubygems.org"

gem "rails", "3.0.0.rc" gem "nokogiri" fi IP "" 0 P When you  run
bundle  install(1)  bundle-install.1.html the first time, bundler
will resolve all of the dependencies, all the way down,  and  in-
stall what you need: IP "" 4 nf

Fetching  gem  metadata  from https://rubygems.org/.........  Re-
solving dependencies...  Installing builder 2.1.2 Installing  ab-
stract 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 In-
stalling 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  In-
stalling  activemodel  3.0.0.rc  Installing arel 0.4.0 Installing
mail 2.2.20 Installing activeresource 3.0.0.rc Installing action-
pack 3.0.0.rc Installing activerecord 3.0.0.rc Installing action-
mailer 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.
fi IP "" 0 P 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 Gem-
file.lock. The next time you  run  bundle  install(1)  bundle-in-
stall.1.html,  bundler  skips  the  dependency resolution and in-
stalls the same gems as it installed last time.  P After checking
in the Gemfile.lock into version control and cloning it on anoth-
er machine, running bundle install(1) bundle-install.1.html  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.   P 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(5).  P To do this, run bundle up-
date --all, 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 re-
quirements  of  new  gems that the gem authors released since the
last time you ran bundle update --all.  SH "UPDATING  A  LIST  OF
GEMS"  Sometimes,  you  want  to  update a single gem in the Gem-
file(5), and leave the rest of the gems that you specified locked
to the versions in the Gemfile.lock.  P For instance, in the sce-
nario above, imagine that nokogiri releases  version  1.4.4,  and
you  want  to update it without updating Rails and all of its de-
pendencies. To do this, run bundle update  nokogiri.   P  Bundler
will update nokogiri and any of its dependencies, but leave alone
Rails and its dependencies.  SH "OVERLAPPING DEPENDENCIES"  Some-
times, multiple gems declared in your Gemfile(5) are satisfied by
the same second-level dependency. For instance, consider the case
of thin and rack-perftools-profiler.  IP "" 4 nf

source "https://rubygems.org"

gem  "thin"  gem  "rack-perftools-profiler" fi IP "" 0 P The thin
gem depends on rack >= 1.0, while rack-perftools-profiler depends
on rack ~> 1.0. If you run bundle install, you get: IP "" 4 nf

Fetching  source  index for https://rubygems.org/ Installing dae-
mons (1.1.0) Installing eventmachine (0.12.10) with native exten-
sions  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 na-
tive extensions Using bundler (1.0.0.rc.3) fi IP "" 0 P  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_profil-
er.   P  In short, by default, when you update a gem using bundle
update, bundler will update all dependencies of that gem, includ-
ing  those  that are also dependencies of another gem.  P To pre-
vent updating shared dependencies, prior to version 1.14 the only
option  was  the  CONSERVATIVE  UPDATING  behavior  in bundle in-
stall(1) bundle-install.1.html: P In this scenario, updating  the
thin  version manually in the Gemfile(5), and then running bundle
install(1) bundle-install.1.html will  only  update  daemons  and
eventmachine, but not rack. For more information, see the CONSER-
VATIVE  UPDATING  section   of   bundle   install(1)   bundle-in-
stall.1.html.   P  Starting with 1.14, specifying the --conserva-
tive option will also prevent shared dependencies from being  up-
dated.   SH  "PATCH  LEVEL  OPTIONS"  Version  1.14  introduced 4
patch-level options that will influence how gem versions are  re-
solved.  One of the following options can be used: --patch, --mi-
nor or --major. --strict can be added to further influence  reso-
lution.   TP  --patch Prefer updating only to next patch version.
TP --minor Prefer updating only to next minor version.  TP  --ma-
jor Prefer updating to next major version (default).  TP --strict
Do not allow any gem to be updated past latest --patch |  --minor
|  --major.   P 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.  P Provid-
ing one of the patch level options  (e.g.  --patch)  changes  the
sort order of the satisfying versions, causing Bundler to consid-
er 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.   P  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 pref-
erence by default (--major) will be "2.0.0, 1.1.1, 1.1.0,  1.0.4,
1.0.3,  1.0.2".   P  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".  P 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".   P
Combining the --strict option with any of the patch level options
will remove any versions beyond the scope of the patch level  op-
tion,  to  ensure that no gem is updated that far.  P 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".  P Gem requirements as de-
fined 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.  SH "PATCH LEVEL
EXAMPLES" Given the following gem specifications: IP "" 4 nf

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 fi IP "" 0 P Gemfile: IP "" 4 nf

gem 'foo' fi IP "" 0 P Gemfile.lock: IP "" 4 nf

foo (1.4.3)
  bar (~> 2.0) bar (2.0.3) fi IP "" 0 P Cases: IP "" 4 nf

#          Command         Line                            Result
------------------------------------------------------------    1
bundle update --patch            'foo 1.4.5', 'bar 2.1.1' 2  bun-
dle 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 up-
date --minor --strict   'foo 1.5.0', 'bar 2.1.1' 5  bundle update
--patch  --strict   'foo 1.4.4', 'bar 2.0.4' fi IP "" 0 P In case
1, bar is upgraded to 2.1.1, a minor  version  increase,  because
the dependency from foo 1.4.5 required it.  P In case 2, only foo
is requested to be unlocked, but bar is also allowed to move  be-
cause  it's  not a declared dependency in the Gemfile.  P 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.  P In case 4, foo is preferred up to a  minor  ver-
sion,  but 1.5.1 won't work because the --strict flag removes bar
3.0.0 from consideration since it's a major increment.  P 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.  SH "RECOMMENDED WORKFLOW" In
general, when working with an application managed  with  bundler,
you  should use the following workflow: IP "o" 4 After you create
your Gemfile(5) for the first time, run IP $  bundle  install  IP
"o"  4 Check the resulting Gemfile.lock into version control IP $
git add Gemfile.lock IP "o" 4 When checking out  this  repository
on  another development machine, run IP $ bundle install IP "o" 4
When checking out this repository on a deployment machine, run IP
$  bundle  install  --deployment IP "o" 4 After changing the Gem-
file(5) to reflect a new or update dependency, run  IP  $  bundle
install IP "o" 4 Make sure to check the updated Gemfile.lock into
version control IP $ git add Gemfile.lock IP "o" 4 If bundle  in-
stall(1)  bundle-install.1.html  reports a conflict, manually up-
date the specific gems that you changed in the  Gemfile(5)  IP  $
bundle  update  rails thin IP "o" 4 If you want to update all the
gems to the latest possible versions that still  match  the  gems
listed in the Gemfile(5), run IP $ bundle update --all IP "" 0

See for descriptions of the following attributes:

|Availability   | runtime/ruby-26  |
|Stability      | Uncommitted      |

This    software    was    built   from   source   available   at
https://github.com/oracle/solaris-userland.  The original  commu-
nity    source    was    downloaded    from    http://cache.ruby-

Further information about this software can be found on the  open
source community website at http://www.ruby-lang.org/.