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

NAME

6       bundle-config - Set bundler configuration options
7

SYNOPSIS

9       bundle config list
10       bundle config [get] NAME
11       bundle config [set] NAME VALUE
12       bundle config unset NAME
13

DESCRIPTION

15       This  command  allows you to interact with Bundler´s configuration sys‐
16       tem.
17
18       Bundler loads configuration settings in this order:
19
20       1.  Local  config  (<project_root>/.bundle/config  or  $BUNDLE_APP_CON‐
21           FIG/config)
22
23       2.  Environmental variables (ENV)
24
25       3.  Global config (~/.bundle/config)
26
27       4.  Bundler default config
28
29
30
31       Executing bundle config list with will print a list of all bundler con‐
32       figuration for the current bundle, and  where  that  configuration  was
33       set.
34
35       Executing bundle config get <name> will print the value of that config‐
36       uration setting, and where it was set.
37
38       Executing bundle config set <name> <value> defaults  to  setting  local
39       configuration  if  executing from within a local application, otherwise
40       it will set global configuration. See --local and --global options  be‐
41       low.
42
43       Executing  bundle  config set --local <name> <value> will set that con‐
44       figuration in the directory for the local application.  The  configura‐
45       tion   will   be   stored  in  <project_root>/.bundle/config.  If  BUN‐
46       DLE_APP_CONFIG is set,  the  configuration  will  be  stored  in  $BUN‐
47       DLE_APP_CONFIG/config.
48
49       Executing  bundle config set --global <name> <value> will set that con‐
50       figuration to the value specified for all bundles executed as the  cur‐
51       rent  user.  The  configuration  will be stored in ~/.bundle/config. If
52       name already is set, name will be overridden and user will be warned.
53
54       Executing bundle config unset <name> will delete the  configuration  in
55       both local and global sources.
56
57       Executing  bundle config unset --global <name> will delete the configu‐
58       ration only from the user configuration.
59
60       Executing bundle config unset --local <name> will delete the configura‐
61       tion only from the local application.
62
63       Executing bundle with the BUNDLE_IGNORE_CONFIG environment variable set
64       will cause it to ignore all configuration.
65

REMEMBERING OPTIONS

67       Flags passed to bundle install or the Bundler runtime, such  as  --path
68       foo  or --without production, are remembered between commands and saved
69       to your local application´s configuration (normally, ./.bundle/config).
70
71       However, this will be changed in bundler 3, so it´s better not to  rely
72       on  this  behavior. If these options must be remembered, it´s better to
73       set them using bundle config (e.g.,  bundle  config  set  --local  path
74       foo).
75
76       The options that can be configured are:
77
78       bin    Creates  a  directory (defaults to ~/bin) and place any executa‐
79              bles from the gem there. These executables run in Bundler´s con‐
80              text.  If  used,  you  might add this directory to your environ‐
81              ment´s PATH variable. For instance, if the rails gem comes  with
82              a rails executable, this flag will create a bin/rails executable
83              that ensures that all referred dependencies will be resolved us‐
84              ing the bundled gems.
85
86       deployment
87              In  deployment mode, Bundler will ´roll-out´ the bundle for pro‐
88              duction use. Please check carefully if you want to have this op‐
89              tion enabled in development or test environments.
90
91       only   A  space-separated  list  of  groups to install only gems of the
92              specified groups.
93
94       path   The location to install the specified gems to. This defaults  to
95              Rubygems´  setting.  Bundler shares this location with Rubygems,
96              gem install ... will have gem installed there,  too.  Therefore,
97              gems  installed  without  a  --path  ... setting will show up by
98              calling gem list. Accordingly, gems installed to other locations
99              will not get listed.
100
101       without
102              A space-separated list of groups referencing gems to skip during
103              installation.
104
105       with   A space-separated list of optional groups  referencing  gems  to
106              include during installation.
107

BUILD OPTIONS

109       You  can use bundle config to give Bundler the flags to pass to the gem
110       installer every time bundler tries to install a particular gem.
111
112       A very common example, the mysql gem, requires Snow  Leopard  users  to
113       pass  configuration  flags  to gem install to specify where to find the
114       mysql_config executable.
115
116
117
118           gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config
119
120
121
122       Since the specific location of that executable can change from  machine
123       to machine, you can specify these flags on a per-machine basis.
124
125
126
127           bundle config set --global build.mysql --with-mysql-config=/usr/local/mysql/bin/mysql_config
128
129
130
131       After  running  this  command,  every time bundler needs to install the
132       mysql gem, it will pass along the flags you specified.
133

CONFIGURATION KEYS

135       Configuration keys in bundler have two forms: the  canonical  form  and
136       the environment variable form.
137
138       For  instance,  passing  the  --without  flag to bundle install(1) bun‐
139       dle-install.1.html prevents  Bundler  from  installing  certain  groups
140       specified  in  the Gemfile(5). Bundler persists this value in app/.bun‐
141       dle/config so that calls to Bundler.setup do not try to find gems  from
142       the  Gemfile that you didn´t install. Additionally, subsequent calls to
143       bundle install(1) bundle-install.1.html remember this setting and  skip
144       those groups.
145
146       The  canonical  form of this configuration is "without". To convert the
147       canonical form to the environment variable  form,  capitalize  it,  and
148       prepend  BUNDLE_.  The  environment  variable form of "without" is BUN‐
149       DLE_WITHOUT.
150
151       Any periods in the configuration keys must be replaced with two  under‐
152       scores when setting it via environment variables. The configuration key
153       local.rack becomes the environment variable BUNDLE_LOCAL__RACK.
154

LIST OF AVAILABLE KEYS

156       The following is a list of all configuration keys  and  their  purpose.
157       You  can  learn  more  about  their operation in bundle install(1) bun‐
158       dle-install.1.html.
159
160allow_deployment_source_credential_changes    (BUNDLE_ALLOW_DEPLOY‐
161           MENT_SOURCE_CREDENTIAL_CHANGES):  When  in  deployment  mode, allow
162           changing   the    credentials    to    a    gem´s    source.    Ex:
163           https://some.host.com/gems/path/     ->     https://user_name:pass‐
164           word@some.host.com/gems/path
165
166allow_offline_install (BUNDLE_ALLOW_OFFLINE_INSTALL): Allow Bundler
167           to use cached data when installing without network access.
168
169auto_clean_without_path (BUNDLE_AUTO_CLEAN_WITHOUT_PATH): Automati‐
170           cally run bundle clean after installing when an explicit  path  has
171           not been set and Bundler is not installing into the system gems.
172
173auto_install  (BUNDLE_AUTO_INSTALL):  Automatically  run bundle in‐
174           stall when gems are missing.
175
176bin (BUNDLE_BIN): Install executables from gems in  the  bundle  to
177           the specified directory. Defaults to false.
178
179cache_all  (BUNDLE_CACHE_ALL):  Cache  all gems, including path and
180           git gems. This needs to be explicitly configured on bundler  1  and
181           bundler 2, but will be the default on bundler 3.
182
183cache_all_platforms  (BUNDLE_CACHE_ALL_PLATFORMS):  Cache  gems for
184           all platforms.
185
186cache_path (BUNDLE_CACHE_PATH): The  directory  that  bundler  will
187           place  cached gems in when running bundle package, and that bundler
188           will look in when installing gems. Defaults to vendor/cache.
189
190clean (BUNDLE_CLEAN): Whether Bundler should run bundle clean auto‐
191           matically after bundle install.
192
193console  (BUNDLE_CONSOLE):  The console that bundle console starts.
194           Defaults to irb.
195
196default_install_uses_path       (BUNDLE_DEFAULT_INSTALL_USES_PATH):
197           Whether  a  bundle  install without an explicit --path argument de‐
198           faults to installing gems in .bundle.
199
200deployment (BUNDLE_DEPLOYMENT): Disallow changes  to  the  Gemfile.
201           When  the Gemfile is changed and the lockfile has not been updated,
202           running Bundler commands will be blocked.
203
204disable_checksum_validation   (BUNDLE_DISABLE_CHECKSUM_VALIDATION):
205           Allow  installing  gems even if they do not match the checksum pro‐
206           vided by RubyGems.
207
208disable_exec_load (BUNDLE_DISABLE_EXEC_LOAD): Stop Bundler from us‐
209           ing load to launch an executable in-process in bundle exec.
210
211disable_local_branch_check (BUNDLE_DISABLE_LOCAL_BRANCH_CHECK): Al‐
212           low Bundler to use a local git override without a branch  specified
213           in the Gemfile.
214
215disable_local_revision_check (BUNDLE_DISABLE_LOCAL_REVISION_CHECK):
216           Allow Bundler to use a local git override without checking  if  the
217           revision present in the lockfile is present in the repository.
218
219disable_shared_gems (BUNDLE_DISABLE_SHARED_GEMS): Stop Bundler from
220           accessing gems installed to RubyGems´ normal location.
221
222disable_version_check (BUNDLE_DISABLE_VERSION_CHECK): Stop  Bundler
223           from   checking   if  a  newer  Bundler  version  is  available  on
224           rubygems.org.
225
226force_ruby_platform (BUNDLE_FORCE_RUBY_PLATFORM): Ignore  the  cur‐
227           rent  machine´s  platform and install only ruby platform gems. As a
228           result, gems with native extensions will be compiled from source.
229
230frozen (BUNDLE_FROZEN): Disallow changes to the Gemfile.  When  the
231           Gemfile  is  changed and the lockfile has not been updated, running
232           Bundler commands will be blocked. Defaults to true  when  --deploy‐
233           ment is used.
234
235gem.github_username  (BUNDLE_GEM__GITHUB_USERNAME):  Sets  a GitHub
236           username or organization to be used in README file when you  create
237           a  new  gem via bundle gem command. It can be overridden by passing
238           an explicit --github-username flag to bundle gem.
239
240gem.push_key (BUNDLE_GEM__PUSH_KEY): Sets the --key  parameter  for
241           gem  push  when  using the rake release command with a private gem‐
242           stash server.
243
244gemfile (BUNDLE_GEMFILE): The name of the file that bundler  should
245           use  as  the Gemfile. This location of this file also sets the root
246           of the project, which is used to resolve relative paths in the Gem‐
247           file,  among  other things. By default, bundler will search up from
248           the current working directory until it finds a Gemfile.
249
250global_gem_cache (BUNDLE_GLOBAL_GEM_CACHE): Whether Bundler  should
251           cache all gems globally, rather than locally to the installing Ruby
252           installation.
253
254ignore_funding_requests (BUNDLE_IGNORE_FUNDING_REQUESTS): When set,
255           no funding requests will be printed.
256
257ignore_messages (BUNDLE_IGNORE_MESSAGES): When set, no post install
258           messages will be printed. To silence a single gem, use dot notation
259           like ignore_messages.httparty true.
260
261init_gems_rb (BUNDLE_INIT_GEMS_RB): Generate a gems.rb instead of a
262           Gemfile when running bundle init.
263
264jobs (BUNDLE_JOBS): The number of gems Bundler can install in  par‐
265           allel. Defaults to the number of available processors.
266
267no_install  (BUNDLE_NO_INSTALL): Whether bundle package should skip
268           installing gems.
269
270no_prune (BUNDLE_NO_PRUNE): Whether Bundler should  leave  outdated
271           gems unpruned when caching.
272
273only  (BUNDLE_ONLY):  A  space-separated  list of groups to install
274           only gems of the specified groups.
275
276path (BUNDLE_PATH): The location on disk where  all  gems  in  your
277           bundle will be located regardless of $GEM_HOME or $GEM_PATH values.
278           Bundle gems not found in this location will be installed by  bundle
279           install.  Defaults  to Gem.dir. When --deployment is used, defaults
280           to vendor/bundle.
281
282path.system (BUNDLE_PATH__SYSTEM):  Whether  Bundler  will  install
283           gems into the default system path (Gem.dir).
284
285path_relative_to_cwd   (BUNDLE_PATH_RELATIVE_TO_CWD)  Makes  --path
286           relative to the CWD instead of the Gemfile.
287
288plugins (BUNDLE_PLUGINS): Enable Bundler´s experimental plugin sys‐
289           tem.
290
291prefer_patch  (BUNDLE_PREFER_PATCH):  Prefer  updating only to next
292           patch version during updates. Makes bundle update calls  equivalent
293           to bundler update --patch.
294
295print_only_version_number (BUNDLE_PRINT_ONLY_VERSION_NUMBER): Print
296           only version number from bundler --version.
297
298redirect (BUNDLE_REDIRECT): The number  of  redirects  allowed  for
299           network requests. Defaults to 5.
300
301retry  (BUNDLE_RETRY):  The number of times to retry failed network
302           requests. Defaults to 3.
303
304setup_makes_kernel_gem_public   (BUNDLE_SETUP_MAKES_KERNEL_GEM_PUB‐
305           LIC):  Have  Bundler.setup  make the Kernel#gem method public, even
306           though RubyGems declares it as private.
307
308shebang (BUNDLE_SHEBANG): The program name that should  be  invoked
309           for  generated  binstubs. Defaults to the ruby install name used to
310           generate the binstub.
311
312silence_deprecations (BUNDLE_SILENCE_DEPRECATIONS): Whether Bundler
313           should  silence  deprecation  warnings  for  behavior  that will be
314           changed in the next major version.
315
316silence_root_warning  (BUNDLE_SILENCE_ROOT_WARNING):  Silence   the
317           warning Bundler prints when installing gems as root.
318
319ssl_ca_cert  (BUNDLE_SSL_CA_CERT): Path to a designated CA certifi‐
320           cate file or folder containing multiple  certificates  for  trusted
321           CAs in PEM format.
322
323ssl_client_cert (BUNDLE_SSL_CLIENT_CERT): Path to a designated file
324           containing a X.509 client certificate and key in PEM format.
325
326ssl_verify_mode (BUNDLE_SSL_VERIFY_MODE): The SSL verification mode
327           Bundler uses when making HTTPS requests. Defaults to verify peer.
328
329suppress_install_using_messages (BUNDLE_SUPPRESS_INSTALL_USING_MES‐
330           SAGES): Avoid printing Using ... messages during installation  when
331           the version of a gem has not changed.
332
333system_bindir  (BUNDLE_SYSTEM_BINDIR):  The location where RubyGems
334           installs binstubs. Defaults to Gem.bindir.
335
336timeout (BUNDLE_TIMEOUT): The seconds allowed before timing out for
337           network requests. Defaults to 10.
338
339update_requires_all_flag (BUNDLE_UPDATE_REQUIRES_ALL_FLAG): Require
340           passing --all to bundle update when everything should  be  updated,
341           and disallow passing no options to bundle update.
342
343user_agent  (BUNDLE_USER_AGENT):  The  custom  user  agent fragment
344           Bundler includes in API requests.
345
346with (BUNDLE_WITH): A :-separated list of groups whose gems bundler
347           should install.
348
349without  (BUNDLE_WITHOUT):  A :-separated list of groups whose gems
350           bundler should not install.
351
352
353
354       In general, you should set these settings per-application by using  the
355       applicable  flag to the bundle install(1) bundle-install.1.html or bun‐
356       dle cache(1) bundle-cache.1.html command.
357
358       You can set them globally either via environment  variables  or  bundle
359       config,  whichever is preferable for your setup. If you use both, envi‐
360       ronment variables will take preference over global settings.
361

LOCAL GIT REPOS

363       Bundler also allows you to work against a git  repository  locally  in‐
364       stead of using the remote version. This can be achieved by setting up a
365       local override:
366
367
368
369           bundle config set --local local.GEM_NAME /path/to/local/git/repository
370
371
372
373       For example, in order to use a local Rack repository, a developer could
374       call:
375
376
377
378           bundle config set --local local.rack ~/Work/git/rack
379
380
381
382       Now  instead of checking out the remote git repository, the local over‐
383       ride will be used. Similar to a path source, every time the  local  git
384       repository  change, changes will be automatically picked up by Bundler.
385       This means a commit in the local git repo will update the  revision  in
386       the Gemfile.lock to the local git repo revision. This requires the same
387       attention as git submodules. Before pushing to the remote, you need  to
388       ensure the local override was pushed, otherwise you may point to a com‐
389       mit that only exists in your local machine. You´ll also need to CGI es‐
390       cape your usernames and passwords as well.
391
392       Bundler  does many checks to ensure a developer won´t work with invalid
393       references. Particularly, we force a developer to specify a  branch  in
394       the  Gemfile  in  order to use this feature. If the branch specified in
395       the Gemfile and the current branch in the local git repository  do  not
396       match,  Bundler  will  abort.  This  ensures that a developer is always
397       working against the correct branches, and prevents  accidental  locking
398       to a different branch.
399
400       Finally,  Bundler  also  ensures  that the current revision in the Gem‐
401       file.lock exists in the local git repository. By  doing  this,  Bundler
402       forces you to fetch the latest changes in the remotes.
403

MIRRORS OF GEM SOURCES

405       Bundler  supports  overriding gem sources with mirrors. This allows you
406       to configure rubygems.org as the gem source in your Gemfile while still
407       using your mirror to fetch gems.
408
409
410
411           bundle config set --global mirror.SOURCE_URL MIRROR_URL
412
413
414
415       For  example,  to  use  a  mirror  of  https://rubygems.org  hosted  at
416       https://example.org:
417
418
419
420           bundle config set --global mirror.https://rubygems.org https://example.org
421
422
423
424       Each mirror also provides a fallback timeout  setting.  If  the  mirror
425       does  not  respond within the fallback timeout, Bundler will try to use
426       the original server instead of the mirror.
427
428
429
430           bundle config set --global mirror.SOURCE_URL.fallback_timeout TIMEOUT
431
432
433
434       For example, to fall back to rubygems.org after 3 seconds:
435
436
437
438           bundle config set --global mirror.https://rubygems.org.fallback_timeout 3
439
440
441
442       The default fallback timeout is 0.1 seconds, but the setting  can  cur‐
443       rently only accept whole seconds (for example, 1, 15, or 30).
444

CREDENTIALS FOR GEM SOURCES

446       Bundler  allows  you to configure credentials for any gem source, which
447       allows you to avoid putting secrets into your Gemfile.
448
449
450
451           bundle config set --global SOURCE_HOSTNAME USERNAME:PASSWORD
452
453
454
455       For example, to save the credentials of  user  claudette  for  the  gem
456       source at gems.longerous.com, you would run:
457
458
459
460           bundle config set --global gems.longerous.com claudette:s00pers3krit
461
462
463
464       Or you can set the credentials as an environment variable like this:
465
466
467
468           export BUNDLE_GEMS__LONGEROUS__COM="claudette:s00pers3krit"
469
470
471
472       For gems with a git source with HTTP(S) URL you can specify credentials
473       like so:
474
475
476
477           bundle config set --global https://github.com/rubygems/rubygems.git username:password
478
479
480
481       Or you can set the credentials as an environment variable like so:
482
483
484
485           export BUNDLE_GITHUB__COM=username:password
486
487
488
489       This is especially useful for private repositories  on  hosts  such  as
490       GitHub, where you can use personal OAuth tokens:
491
492
493
494           export BUNDLE_GITHUB__COM=abcd0123generatedtoken:x-oauth-basic
495
496
497
498       Note  that  any  configured credentials will be redacted by informative
499       commands such as bundle config list or bundle config  get,  unless  you
500       use the --parseable flag. This is to avoid unintentionally leaking cre‐
501       dentials when copy-pasting bundler output.
502
503       Also note that to guarantee a sane mapping  between  valid  environment
504       variable names and valid host names, bundler makes the following trans‐
505       formations:
506
507       •   Any - characters in a host name are mapped to a triple  dash  (___)
508           in the corresponding environment variable.
509
510       •   Any . characters in a host name are mapped to a double dash (__) in
511           the corresponding environment variable.
512
513
514
515       This means that if you have a gem server named my.gem-host.com,  you´ll
516       need  to  use the BUNDLE_MY__GEM___HOST__COM variable to configure cre‐
517       dentials for it through ENV.
518

CONFIGURE BUNDLER DIRECTORIES

520       Bundler´s home, config, cache and plugin directories  are  able  to  be
521       configured  through  environment  variables.  The  default location for
522       Bundler´s home directory is ~/.bundle, which  all  directories  inherit
523       from by default. The following outlines the available environment vari‐
524       ables and their default values
525
526
527
528           BUNDLE_USER_HOME : $HOME/.bundle
529           BUNDLE_USER_CACHE : $BUNDLE_USER_HOME/cache
530           BUNDLE_USER_CONFIG : $BUNDLE_USER_HOME/config
531           BUNDLE_USER_PLUGIN : $BUNDLE_USER_HOME/plugin
532
533
534
535
536
537
538                                 October 2022                 BUNDLE-CONFIG(1)
Impressum