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 1.
53
54       --retry=[<number>]
55              Retry failed network or git requests for number times.
56
57       --quiet
58              Only output warnings and errors.
59
60       --redownload
61              Force downloading every gem.
62
63       --patch
64              Prefer updating only to next patch version.
65
66       --minor
67              Prefer updating only to next minor version.
68
69       --major
70              Prefer updating to next major version (default).
71
72       --strict
73              Do not allow any gem to be updated past latest --patch | --minor
74              | --major.
75
76       --conservative
77              Use bundle install conservative update behavior and do not allow
78              indirect dependencies to be updated.
79

UPDATING ALL GEMS

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

UPDATING A LIST OF GEMS

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

OVERLAPPING DEPENDENCIES

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

PATCH LEVEL OPTIONS

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

PATCH LEVEL EXAMPLES

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