1BUNDLE-UPDATE(1)                                              BUNDLE-UPDATE(1)
2
3
4

NAME

6       bundle-update - Update your gems to the latest available versions
7

SYNOPSIS

9       bundle  update  *gems  [--all] [--group=NAME] [--source=NAME] [--local]
10       [--ruby] [--bundler[=VERSION]] [--full-index]  [--jobs=JOBS]  [--quiet]
11       [--patch|--minor|--major] [--redownload] [--strict] [--conservative]
12

DESCRIPTION

14       Update  the  gems specified (all gems, if --all flag is used), ignoring
15       the previously installed gems specified in the  Gemfile.lock.  In  gen‐
16       eral, you should use bundle install(1) bundle-install.1.html to install
17       the same exact gems and versions across machines.
18
19       You would use bundle update to explicitly update the version of a gem.
20

OPTIONS

22       --all  Update all gems specified in Gemfile.
23
24       --group=<name>, -g=[<name>]
25              Only update the gems in the specified group. For  instance,  you
26              can  update all gems in the development group with bundle update
27              --group development. You  can  also  call  bundle  update  rails
28              --group  test  to  update the rails gem and all gems in the test
29              group, for example.
30
31       --source=<name>
32              The name of a :git or :path source used in the  Gemfile(5).  For
33              instance,        with        a        :git       source       of
34              http://github.com/rails/rails.git, you would call bundle  update
35              --source rails
36
37       --local
38              Do  not attempt to fetch gems remotely and use the gem cache in‐
39              stead.
40
41       --ruby Update the locked version of Ruby  to  the  current  version  of
42              Ruby.
43
44       --bundler
45              Update the locked version of bundler to the invoked bundler ver‐
46              sion.
47
48       --full-index
49              Fall back to using the single-file index of all gems.
50
51       --jobs=[<number>], -j[<number>]
52              Specify the number of jobs to run in parallel.  The  default  is
53              the number of available processors.
54
55       --retry=[<number>]
56              Retry failed network or git requests for number times.
57
58       --quiet
59              Only output warnings and errors.
60
61       --redownload
62              Force downloading every gem.
63
64       --patch
65              Prefer updating only to next patch version.
66
67       --minor
68              Prefer updating only to next minor version.
69
70       --major
71              Prefer updating to next major version (default).
72
73       --strict
74              Do not allow any gem to be updated past latest --patch | --minor
75              | --major.
76
77       --conservative
78              Use bundle install conservative update behavior and do not allow
79              indirect dependencies to be updated.
80

UPDATING ALL GEMS

82       If  you run bundle update --all, bundler will ignore any previously in‐
83       stalled gems and resolve all dependencies again  based  on  the  latest
84       versions of all gems available in the sources.
85
86       Consider the following Gemfile(5):
87
88
89
90           source "https://rubygems.org"
91
92           gem "rails", "3.0.0.rc"
93           gem "nokogiri"
94
95
96
97       When  you  run  bundle install(1) bundle-install.1.html the first time,
98       bundler will resolve all of the dependencies, all the way down, and in‐
99       stall what you need:
100
101
102
103           Fetching gem metadata from https://rubygems.org/.........
104           Resolving dependencies...
105           Installing builder 2.1.2
106           Installing abstract 1.0.0
107           Installing rack 1.2.8
108           Using bundler 1.7.6
109           Installing rake 10.4.0
110           Installing polyglot 0.3.5
111           Installing mime-types 1.25.1
112           Installing i18n 0.4.2
113           Installing mini_portile 0.6.1
114           Installing tzinfo 0.3.42
115           Installing rack-mount 0.6.14
116           Installing rack-test 0.5.7
117           Installing treetop 1.4.15
118           Installing thor 0.14.6
119           Installing activesupport 3.0.0.rc
120           Installing erubis 2.6.6
121           Installing activemodel 3.0.0.rc
122           Installing arel 0.4.0
123           Installing mail 2.2.20
124           Installing activeresource 3.0.0.rc
125           Installing actionpack 3.0.0.rc
126           Installing activerecord 3.0.0.rc
127           Installing actionmailer 3.0.0.rc
128           Installing railties 3.0.0.rc
129           Installing rails 3.0.0.rc
130           Installing nokogiri 1.6.5
131
132           Bundle complete! 2 Gemfile dependencies, 26 gems total.
133           Use `bundle show [gemname]` to see where a bundled gem is installed.
134
135
136
137       As  you  can see, even though you have two gems in the Gemfile(5), your
138       application needs 26 different gems in order to run. Bundler  remembers
139       the  exact versions it installed in Gemfile.lock. The next time you run
140       bundle install(1) bundle-install.1.html, bundler skips  the  dependency
141       resolution and installs the same gems as it installed last time.
142
143       After  checking in the Gemfile.lock into version control and cloning it
144       on another machine,  running  bundle  install(1)  bundle-install.1.html
145       will  still  install  the  gems that you installed last time. You don´t
146       need to worry that a new release of erubis or mail changes the gems you
147       use.
148
149       However,  from  time to time, you might want to update the gems you are
150       using to the newest versions that still match the  gems  in  your  Gem‐
151       file(5).
152
153       To  do  this,  run  bundle  update  --all,  which  will ignore the Gem‐
154       file.lock, and resolve all the dependencies again. Keep  in  mind  that
155       this  process  can  result  in  a significantly different set of the 25
156       gems, based on the requirements of new gems that the  gem  authors  re‐
157       leased since the last time you ran bundle update --all.
158

UPDATING A LIST OF GEMS

160       Sometimes, you want to update a single gem in the Gemfile(5), and leave
161       the rest of the gems that you specified locked to the versions  in  the
162       Gemfile.lock.
163
164       For  instance,  in  the  scenario above, imagine that nokogiri releases
165       version 1.4.4, and you want to update it without updating Rails and all
166       of its dependencies. To do this, run bundle update nokogiri.
167
168       Bundler  will  update  nokogiri  and any of its dependencies, but leave
169       alone Rails and its dependencies.
170

OVERLAPPING DEPENDENCIES

172       Sometimes, multiple gems declared in your Gemfile(5) are  satisfied  by
173       the  same  second-level  dependency. For instance, consider the case of
174       thin and rack-perftools-profiler.
175
176
177
178           source "https://rubygems.org"
179
180           gem "thin"
181           gem "rack-perftools-profiler"
182
183
184
185       The thin gem depends on rack >= 1.0, while rack-perftools-profiler  de‐
186       pends on rack ~> 1.0. If you run bundle install, you get:
187
188
189
190           Fetching source index for https://rubygems.org/
191           Installing daemons (1.1.0)
192           Installing eventmachine (0.12.10) with native extensions
193           Installing open4 (1.0.1)
194           Installing perftools.rb (0.4.7) with native extensions
195           Installing rack (1.2.1)
196           Installing rack-perftools_profiler (0.0.2)
197           Installing thin (1.2.7) with native extensions
198           Using bundler (1.0.0.rc.3)
199
200
201
202       In this case, the two gems have their own set of dependencies, but they
203       share rack in common. If you run bundle update thin, bundler  will  up‐
204       date  daemons,  eventmachine  and rack, which are dependencies of thin,
205       but  not   open4   or   perftools.rb,   which   are   dependencies   of
206       rack-perftools_profiler.  Note that bundle update thin will update rack
207       even though it´s also a dependency of rack-perftools_profiler.
208
209       In short, by default, when  you  update  a  gem  using  bundle  update,
210       bundler  will update all dependencies of that gem, including those that
211       are also dependencies of another gem.
212
213       To prevent updating indirect dependencies, prior to  version  1.14  the
214       only option was the CONSERVATIVE UPDATING behavior in bundle install(1)
215       bundle-install.1.html:
216
217       In this scenario, updating the thin version manually in the Gemfile(5),
218       and  then running bundle install(1) bundle-install.1.html will only up‐
219       date daemons and eventmachine, but not rack. For more information,  see
220       the  CONSERVATIVE  UPDATING  section  of  bundle  install(1) bundle-in‐
221       stall.1.html.
222
223       Starting with 1.14, specifying the --conservative option will also pre‐
224       vent indirect dependencies from being updated.
225

PATCH LEVEL OPTIONS

227       Version  1.14  introduced 4 patch-level options that will influence how
228       gem versions are resolved. One of the following options  can  be  used:
229       --patch, --minor or --major. --strict can be added to further influence
230       resolution.
231
232       --patch
233              Prefer updating only to next patch version.
234
235       --minor
236              Prefer updating only to next minor version.
237
238       --major
239              Prefer updating to next major version (default).
240
241       --strict
242              Do not allow any gem to be updated past latest --patch | --minor
243              | --major.
244
245       When  Bundler is resolving what versions to use to satisfy declared re‐
246       quirements in the Gemfile or in parent gems, it looks up all  available
247       versions,  filters out any versions that don´t satisfy the requirement,
248       and then, by default, sorts them from  newest  to  oldest,  considering
249       them in that order.
250
251       Providing  one  of  the  patch level options (e.g. --patch) changes the
252       sort order of the satisfying versions, causing Bundler to consider  the
253       latest --patch or --minor version available before other versions. Note
254       that versions outside the stated patch level could still be resolved to
255       if necessary to find a suitable dependency graph.
256
257       For  example,  if gem ´foo´ is locked at 1.0.2, with no gem requirement
258       defined in the Gemfile, and versions 1.0.3, 1.0.4, 1.1.0, 1.1.1,  2.0.0
259       all exist, the default order of preference by default (--major) will be
260       "2.0.0, 1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2".
261
262       If the --patch option is used, the order of preference will  change  to
263       "1.0.4, 1.0.3, 1.0.2, 1.1.1, 1.1.0, 2.0.0".
264
265       If  the  --minor option is used, the order of preference will change to
266       "1.1.1, 1.1.0, 1.0.4, 1.0.3, 1.0.2, 2.0.0".
267
268       Combining the --strict option with any of the patch level options  will
269       remove  any versions beyond the scope of the patch level option, to en‐
270       sure that no gem is updated that far.
271
272       To continue the previous example, if both --patch and --strict  options
273       are used, the available versions for resolution would be "1.0.4, 1.0.3,
274       1.0.2". If --minor and --strict are used, it would  be  "1.1.1,  1.1.0,
275       1.0.4, 1.0.3, 1.0.2".
276
277       Gem  requirements as defined in the Gemfile will still be the first de‐
278       termining factor for what versions are available. If the  gem  require‐
279       ment  for foo in the Gemfile is ´~> 1.0´, that will accomplish the same
280       thing as providing the --minor and --strict options.
281

PATCH LEVEL EXAMPLES

283       Given the following gem specifications:
284
285
286
287           foo 1.4.3, requires: ~> bar 2.0
288           foo 1.4.4, requires: ~> bar 2.0
289           foo 1.4.5, requires: ~> bar 2.1
290           foo 1.5.0, requires: ~> bar 2.1
291           foo 1.5.1, requires: ~> bar 3.0
292           bar with versions 2.0.3, 2.0.4, 2.1.0, 2.1.1, 3.0.0
293
294
295
296       Gemfile:
297
298
299
300           gem ´foo´
301
302
303
304       Gemfile.lock:
305
306
307
308           foo (1.4.3)
309             bar (~> 2.0)
310           bar (2.0.3)
311
312
313
314       Cases:
315
316
317
318           #  Command Line                     Result
319           ------------------------------------------------------------
320           1  bundle update --patch            ´foo 1.4.5´, ´bar 2.1.1´
321           2  bundle update --patch foo        ´foo 1.4.5´, ´bar 2.1.1´
322           3  bundle update --minor            ´foo 1.5.1´, ´bar 3.0.0´
323           4  bundle update --minor --strict   ´foo 1.5.0´, ´bar 2.1.1´
324           5  bundle update --patch --strict   ´foo 1.4.4´, ´bar 2.0.4´
325
326
327
328       In case 1, bar is upgraded to 2.1.1, a minor version increase,  because
329       the dependency from foo 1.4.5 required it.
330
331       In  case  2,  only foo is requested to be unlocked, but bar is also al‐
332       lowed to move because it´s not a declared dependency in the Gemfile.
333
334       In case 3, bar goes up a whole major release, because a minor  increase
335       is  preferred now for foo, and when it goes to 1.5.1, it requires 3.0.0
336       of bar.
337
338       In case 4, foo is preferred up to a minor version, but 1.5.1 won´t work
339       because  the  --strict  flag removes bar 3.0.0 from consideration since
340       it´s a major increment.
341
342       In case 5, both foo and bar have any minor or major increments  removed
343       from  consideration  because of the --strict flag, so the most they can
344       move is up to 1.4.4 and 2.0.4.
345
347       In general, when working with an application managed with bundler,  you
348       should use the following workflow:
349
350       •   After you create your Gemfile(5) for the first time, run
351
352           $ bundle install
353
354       •   Check the resulting Gemfile.lock into version control
355
356           $ git add Gemfile.lock
357
358       •   When  checking  out this repository on another development machine,
359           run
360
361           $ bundle install
362
363       •   When checking out this repository on a deployment machine, run
364
365           $ bundle install --deployment
366
367       •   After changing the Gemfile(5) to reflect a  new  or  update  depen‐
368           dency, run
369
370           $ bundle install
371
372       •   Make sure to check the updated Gemfile.lock into version control
373
374           $ git add Gemfile.lock
375
376       •   If bundle install(1) bundle-install.1.html reports a conflict, man‐
377           ually update the specific gems that you changed in the Gemfile(5)
378
379           $ bundle update rails thin
380
381       •   If you want to update all the gems to the latest possible  versions
382           that still match the gems listed in the Gemfile(5), run
383
384           $ bundle update --all
385
386
387
388
389
390
391                                 December 2021                BUNDLE-UPDATE(1)
Impressum