1BUNDLE-CONFIG(1) BUNDLE-CONFIG(1)
2
6 bundle-config - Set bundler configuration options
7
9 bundle config [name [value]]
10
12 This command allows you to interact with bundler´s configuration sys‐
13 tem. Bundler retrieves its configuration from the local application
14 (app/.bundle/config), environment variables, and the user´s home direc‐
15 tory (~/.bundle/config), in that order of priority.
16 Executing bundle config with no parameters will print a list of all
18 bundler configuration for the current bundle, and where that configura‐
19 tion was set.
20 Executing bundle config <name> will print the value of that configura‐
22 tion setting, and where it was set.
23 Executing bundle config <name> <value> will set that configuration to
25 the value specified for all bundles executed as the current user. The
26 configuration will be stored in ~/.bundle/config. If name already is
27 set, name will be overridden and user will be warned.
28 Executing bundle config --global <name> <value> works the same as
30 above.
31 Executing bundle config --local <name> <value> will set that configura‐
33 tion to the local application. The configuration will be stored in
34 app/.bundle/config.
35 Executing bundle config --delete <name> will delete the configuration
37 in both local and global sources. Not compatible with --global or
38 --local flag.
39 Executing bundle with the BUNDLE_IGNORE_CONFIG environment variable set
41 will cause it to ignore all configuration.
42
44 You can use bundle config to give bundler the flags to pass to the gem
45 installer every time bundler tries to install a particular gem.
46 A very common example, the mysql gem, requires Snow Leopard users to
48 pass configuration flags to gem install to specify where to find the
49 mysql_config executable.
50 gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config
54 Since the specific location of that executable can change from machine
58 to machine, you can specify these flags on a per-machine basis.
59 bundle config build.mysql --with-mysql-config=/usr/local/mysql/bin/mysql_config
63 After running this command, every time bundler needs to install the
67 mysql gem, it will pass along the flags you specified.
68
70 Configuration keys in bundler have two forms: the canonical form and
71 the environment variable form.
72 For instance, passing the --without flag to bundle install(1) bun‐
74 dle-install.1.html prevents Bundler from installing certain groups
75 specified in the Gemfile(5). Bundler persists this value in app/.bun‐
76 dle/config so that calls to Bundler.setup do not try to find gems from
77 the Gemfile that you didn´t install. Additionally, subsequent calls to
78 bundle install(1) bundle-install.1.html remember this setting and skip
79 those groups.
80 The canonical form of this configuration is "without". To convert the
82 canonical form to the environment variable form, capitalize it, and
83 prepend BUNDLE_. The environment variable form of "without" is BUN‐
84 DLE_WITHOUT.
85
87 The following is a list of all configuration keys and their purpose.
88 You can learn more about their operation in bundle install(1) bun‐
89 dle-install.1.html.
90 path (BUNDLE_PATH)
92 The location on disk to install gems. Defaults to $GEM_HOME in
93 development and vendor/bundler when --deployment is used
94 frozen (BUNDLE_FROZEN)
96 Disallow changes to the Gemfile. Defaults to true when --deploy‐
97 ment is used.
98 without (BUNDLE_WITHOUT)
100 A :-separated list of groups whose gems bundler should not
101 install
102 bin (BUNDLE_BIN)
104 Install executables from gems in the bundle to the specified
105 directory. Defaults to false.
106 ssl_ca_cert (BUNDLE_SSL_CA_CERT)
108 Path to a designated CA certificate file or folder containing
109 multiple certificates for trusted CAs in PEM format.
110 ssl_client_cert (BUNDLE_SSL_CLIENT_CERT)
112 Path to a designated file containing a X.509 client certificate
113 and key in PEM format.
114 In general, you should set these settings per-application by using the
116 applicable flag to the bundle install(1) bundle-install.1.html command.
117 You can set them globally either via environment variables or bundle
119 config, whichever is preferable for your setup. If you use both, envi‐
120 ronment variables will take preference over global settings.
121 An additional setting is available only as an environment variable:
123 BUNDLE_GEMFILE
125 The name of the file that bundler should use as the Gemfile.
126 This location of this file also sets the root of the project,
127 which is used to resolve relative paths in the Gemfile, among
128 other things. By default, bundler will search up from the cur‐
129 rent working directory until it finds a Gemfile.
130 Bundler will ignore any BUNDLE_GEMFILE entries in local or global con‐
132 figuration files.
133
135 Bundler also allows you to work against a git repository locally
136 instead of using the remote version. This can be achieved by setting up
137 a local override:
138 bundle config local.GEM_NAME /path/to/local/git/repository
142 For example, in order to use a local Rack repository, a developer could
146 call:
147 bundle config local.rack ~/Work/git/rack
151 Now instead of checking out the remote git repository, the local over‐
155 ride will be used. Similar to a path source, every time the local git
156 repository change, changes will be automatically picked up by Bundler.
157 This means a commit in the local git repo will update the revision in
158 the Gemfile.lock to the local git repo revision. This requires the same
159 attention as git submodules. Before pushing to the remote, you need to
160 ensure the local override was pushed, otherwise you may point to a com‐
161 mit that only exists in your local machine.
162 Bundler does many checks to ensure a developer won´t work with invalid
164 references. Particularly, we force a developer to specify a branch in
165 the Gemfile in order to use this feature. If the branch specified in
166 the Gemfile and the current branch in the local git repository do not
167 match, Bundler will abort. This ensures that a developer is always
168 working against the correct branches, and prevents accidental locking
169 to a different branch.
170 Finally, Bundler also ensures that the current revision in the Gem‐
172 file.lock exists in the local git repository. By doing this, Bundler
173 forces you to fetch the latest changes in the remotes.
174
176 Bundler supports overriding gem sources with mirrors. This allows you
177 to configure rubygems.org as the gem source in your Gemfile while still
178 using your mirror to fetch gems.
179 bundle config mirror.SOURCE_URL MIRROR_URL
183 For example, to use a mirror of rubygems.org hosted at
187 bundle config mirror.http://rubygems.org http://rubygems-mirror.org
191
195 Bundler allows you to configure credentials for any gem source, which
196 allows you to avoid putting secrets into your Gemfile.
197 bundle config SOURCE_URL USERNAME:PASSWORD
201 For example, to save the credentials of user claudette for the gem
205 source at gems.longerous.com, you would run:
206 bundle config https://gems.longerous.com/ claudette:s00pers3krit
210 December 2014 BUNDLE-CONFIG(1)