Bundler helps in managing gem dependencies of ruby projects. You can specify which gems and versions you need, bundler will install them and load them at runtime. Bundler ensures that gems you need are present in the environment you need.
Bundle configurations
Bundler gets its configurations from local application (app/.bundle/config), environment variables and user’s home directory (~/.bundle/config) in the order of priority.
To list all bundler configurations for the current bundle, run bundle config without any parameters. You will also get the location where the value is set.
1 2$ bundle config 3Settings are listed in order of priority. The top value will be used. 4
You might see different result based on configuration of bundler on your machine.
To get value for the specific configuration setting, run bundle config with name.
1 2$ bundle config disable_multisource 3Settings for `disable_multisource` in order of priority. The top value will be used 4You have not configured a value for `disable_multistore` 5
Setting Configuration
To set the value of the configuration setting, use bundle config with name and value. Configuration will be stored in ~/.bundle/config.
1 2$ bundle config build.pg --with-pg-config=/opt/local/lib/postgresql91/bin/pg_config 3 4$ bundle config 5Settings are listed in order of priority. The top value will be used. 6build.pg 7Set for the current user (/Users/username/.bundle/config): "--with-pg-config=/opt/local/lib/postgresql91/bin/pg_config" 8
If any config already has a value, it will be overwritten directly and user will be warned.
1 2$ bundle config build.pg --with-pg-config=/usr/pgsql-9.1/bin/pg_config 3You are replacing the current global value of build.pg, which is currently "--with-pg-config=/opt/local/lib/postgresql91/bin/pg_config" 4
Application level configuration
By default setting configuration value will set it for all projects on the machine. You can set configurations specific to local application with --local option. This will store value in app/.bundle/config.
1 2$ bundle config --local auto_install false 3You are replacing the current local value of auto_install, which is currently nil 4 5$ bundle config auto_install 6Settings for `auto_install` in order of priority. The top value will be used 7Set for your local app (/Users/username/Documents/Workspace/app-name/.bundle/config): "false" 8Set for the current user (/Users/username/.bundle/config): "true" 9
You can run bundle config with --global. This will set values at global level i.e. across all applications on the machine. It will be similar to running bundle config without any options.
Deleting configuration
You can delete configuration with --delete option.
1 2$ bundle config --delete auto_install 3$ bundle config 4Settings are listed in order of priority. The top value will be used. 5disable_multisource 6Set for the current user (/Users/username/.bundle/config): "true" 7 8build.pg 9Set for the current user (/Users/username/.bundle/config): "--with-pg-config=/usr/pgsql-9.1/bin/pg_config" 10
This is not compatible with --local and --global. This will delete configuration from local and global resources.
Build Options
You can pass the flags required for installing particular gem to bundler with bundle config.
Many El Capitan users face an issue while installing eventmachine gem. The issue can be resolved by providing path to OpenSSL include directory while installing eventmachine.
1 2$ gem install eventmachine -v '1.0.8' -- --with-cppflags=-I/usr/local/opt/openssl/include 3
As location of configuration will vary from machine to machine, we can set this with bundle config.
1 2$ bundle config build.eventmachine --with-cppflags=-I/usr/local/opt/openssl/include 3
Now bundler will pick this configuration while installing eventmachine gem.
Configuration keys
Various configuration keys are available with bundler. These keys are available in two forms. You can specify them in canonical form with bundle config or set them in environment variable form. Following are canonical forms and their usage. Corresponding environment variables are specified in bracket.
auto_install
Setting auto_install config will enable automatic installing of gems instead of raising an error. This applies to show, binstubs, outdated, exec, open, console, license, clean commands.
Example, When you try to run bundle show for the gem which is not yet installed you will get an error.
1 2$ bundle show pg 3Could not find gem 'pg'. 4
You can set auto_install to remove this error and install gem.
1 2$ bundle config auto_install true 3 4$ bundle show pg 5# Gem will get installed 6/Users/username/.rvm/gems/ruby-2.2.2@gemset-auto/gems/pg-0.17.1 7
path (BUNDLE_PATH)
You can specify location to install your gems. Default path is $GEM_HOME for development and vendor/bundle when --deployment is used.
1 2$ bundle config path NEW_PATH 3$ bundle install 4# Gems will get installed 5# 6# 7Bundle complete! 4 Gemfile dependencies, 35 gems now installed. 8Bundled gems are installed into NEW_PATH. 9
frozen (BUNDLE_FROZEN)
You can freeze changes to your Gemfile.
1 2$ bundle config frozen true 3
If frozen is set and you try to run bundle install with changed Gemfile, you will get following warning.
1 2You are trying to install in deployment mode after changing 3your Gemfile. Run `bundle install` elsewhere and add the 4updated Gemfile.lock to version control. 5 6If this is a development machine, remove the /Users/username/Documents/Workspace/app-name/Gemfile freeze 7by running `bundle install --no-deployment`. 8 9You have added to the Gemfile: 10* minitest-reporters 11
without (BUNDLE_WITHOUT)
You can skip installing groups of gems with bundle install. Specify : separated group names whose gems bundler should not install.
1 2$ bundle config --local without development:test 3 4$ bundle install 5# This will install gems skipping development and test group gems. 6
bin (BUNDLE_BIN)
You can set the directory to install executables from gems in the bundle.
1 2$ bundle config bin NEW_PATH 3 4$ bundle install 5# This will install executables in NEW_PATH 6
gemfile (BUNDLE_GEMFILE)
You can set the file which bundler should use as theGemfile. By default, bundler will use Gemfile. The location of this file also sets the root of the project, which is used to resolve relative paths in the Gemfile.
1 2$ bundle config gemfile Gemfile-rails4 3 4$ bundle install 5# This will install gems from Gemfile-rails4 file. 6
ssl_ca_cert (BUNDLE_SSL_CA_CERT)
This specifies path to a designated CA certificate file or folder containing multiple certificates for trusted CAs in PEM format. You can specify your own https sources in Gemfile with corresponding certificates specified via bundle config.
1 2$ bundle config ssl_ca_cert NEW_CERTIFICATE_PATH 3
ssl_client_cert (BUNDLE_SSL_CLIENT_CERT)
This specifies path to a designated file containing a X.509 client certificate and key in PEM format.
1 2$ bundle config ssl_client_cert NEW_CERTIFICATE_PATH 3
cache_path (BUNDLE_CACHE_PATH)
You can set the path to place cached gems while running bundle package.
1 2$ bundle config cache_path vendor/new-cache-path 3 4$ bundle package 5Using colorize 0.7.7 6Using pg 0.17.1 7Using bundler 1.11.2 8Updating files in vendor/new-cache-path 9 * colorize-0.7.7.gem 10 * pg-0.17.1.gem 11Bundle complete! 2 Gemfile dependencies, 3 gems now installed. 12Use `bundle show [gemname]` to see where a bundled gem is installed. 13Updating files in vendor/new-cache-path 14
disable_multisource (BUNDLE_DISABLE_MULTISOURCE)
When set, Gemfiles containing multiple sources will produce an error instead of a warning.
With Gemfile,
1 2source 'https://rubygems.org' 3source 'http://gems.github.com' 4 5ruby '2.2.2' 6
When you try to run bundle install, you will get warning.
1 2$ bundle install 3Warning: this Gemfile contains multiple primary sources. Using `source` more than once without a block is a security risk, and may result in installing unexpected gems. To resolve this warning, use a block to indicate which gems should come from the secondary source. To upgrade this warning to an error, run `bundle config disable_multisource true`. 4
1 2$ bundle config --local disable_multisource true 3 4$ bundle install 5[!] There was an error parsing `Gemfile`: Warning: this Gemfile contains multiple primary sources. Each source after the first must include a block to indicate which gems should come from that source. To downgrade this error to a warning, run `bundle config --delete disable_multisource`. Bundler cannot continue. 6 7 # from /Users/username/Documents/Workspace//Gemfile:2 8 # ------------------------------------------- 9 # source 'https://rubygems.org' 10 > source 'http://gems.github.com' 11 # 12 # ------------------------------------------- 13
To ignore all bundle config on the machine and run bundle install, set BUNDLE_IGNORE_CONFIG environment variable.