156 lines
6.5 KiB
Markdown
156 lines
6.5 KiB
Markdown
bundle-config(1) -- Set bundler configuration options
|
|
=====================================================
|
|
|
|
## SYNOPSIS
|
|
|
|
`bundle config` [<name> [<value>]]
|
|
|
|
## DESCRIPTION
|
|
|
|
This command allows you to interact with bundler's configuration system.
|
|
Bundler retrieves its configuration from the local application (`app/.bundle/config`),
|
|
environment variables, and the user's home directory (`~/.bundle/config`),
|
|
in that order of priority.
|
|
|
|
Executing `bundle config` with no parameters will print a list of all
|
|
bundler configuration for the current bundle, and where that configuration
|
|
was set.
|
|
|
|
Executing `bundle config <name>` will print the value of that configuration
|
|
setting, and where it was set.
|
|
|
|
Executing `bundle config <name> <value>` will set that configuration to the
|
|
value specified for all bundles executed as the current user. The configuration
|
|
will be stored in `~/.bundle/config`. If <name> already is set, <name> will be
|
|
overridden and user will be warned.
|
|
|
|
Executing `bundle config --global <name> <value>` works the same as above.
|
|
|
|
Executing `bundle config --local <name> <value>` will set that configuration to
|
|
the local application. The configuration will be stored in `app/.bundle/config`.
|
|
|
|
Executing `bundle config --delete <name>` will delete the configuration in both
|
|
local and global sources. Not compatible with --global or --local flag.
|
|
|
|
Executing bundle with the `BUNDLE_IGNORE_CONFIG` environment variable set will
|
|
cause it to ignore all configuration.
|
|
|
|
## BUILD OPTIONS
|
|
|
|
You can use `bundle config` to give bundler the flags to pass to the gem
|
|
installer every time bundler tries to install a particular gem.
|
|
|
|
A very common example, the `mysql` gem, requires Snow Leopard users to
|
|
pass configuration flags to `gem install` to specify where to find the
|
|
`mysql_config` executable.
|
|
|
|
gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config
|
|
|
|
Since the specific location of that executable can change from machine
|
|
to machine, you can specify these flags on a per-machine basis.
|
|
|
|
bundle config build.mysql --with-mysql-config=/usr/local/mysql/bin/mysql_config
|
|
|
|
After running this command, every time bundler needs to install the
|
|
`mysql` gem, it will pass along the flags you specified.
|
|
|
|
## CONFIGURATION KEYS
|
|
|
|
Configuration keys in bundler have two forms: the canonical form and the
|
|
environment variable form.
|
|
|
|
For instance, passing the `--without` flag to [bundle install(1)][bundle-install]
|
|
prevents Bundler from installing certain groups specified in the Gemfile(5). Bundler
|
|
persists this value in `app/.bundle/config` so that calls to `Bundler.setup`
|
|
do not try to find gems from the `Gemfile` that you didn't install. Additionally,
|
|
subsequent calls to [bundle install(1)][bundle-install] remember this setting and skip those
|
|
groups.
|
|
|
|
The canonical form of this configuration is `"without"`. To convert the canonical
|
|
form to the environment variable form, capitalize it, and prepend `BUNDLE_`. The
|
|
environment variable form of `"without"` is `BUNDLE_WITHOUT`.
|
|
|
|
## LIST OF AVAILABLE KEYS
|
|
|
|
The following is a list of all configuration keys and their purpose. You can
|
|
learn more about their operation in [bundle install(1)][bundle-install].
|
|
|
|
* `path` (`BUNDLE_PATH`):
|
|
The location on disk to install gems. Defaults to `$GEM_HOME` in development
|
|
and `vendor/bundler` when `--deployment` is used
|
|
* `frozen` (`BUNDLE_FROZEN`):
|
|
Disallow changes to the `Gemfile`. Defaults to `true` when `--deployment`
|
|
is used.
|
|
* `without` (`BUNDLE_WITHOUT`):
|
|
A `:`-separated list of groups whose gems bundler should not install
|
|
* `bin` (`BUNDLE_BIN`):
|
|
Install executables from gems in the bundle to the specified directory.
|
|
Defaults to `false`.
|
|
* `ssl_ca_cert` (`BUNDLE_SSL_CA_CERT`):
|
|
Path to a designated CA certificate file or folder containing multiple
|
|
certificates for trusted CAs in PEM format.
|
|
* `ssl_client_cert` (`BUNDLE_SSL_CLIENT_CERT`):
|
|
Path to a designated file containing a X.509 client certificate
|
|
and key in PEM format.
|
|
|
|
In general, you should set these settings per-application by using the applicable
|
|
flag to the [bundle install(1)][bundle-install] command.
|
|
|
|
You can set them globally either via environment variables or `bundle config`,
|
|
whichever is preferable for your setup. If you use both, environment variables
|
|
will take preference over global settings.
|
|
|
|
An additional setting is available only as an environment variable:
|
|
|
|
* `BUNDLE_GEMFILE`:
|
|
The name of the file that bundler should use as the `Gemfile`. This location
|
|
of this file also sets the root of the project, which is used to resolve
|
|
relative paths in the `Gemfile`, among other things. By default, bundler
|
|
will search up from the current working directory until it finds a
|
|
`Gemfile`.
|
|
|
|
Bundler will ignore any `BUNDLE_GEMFILE` entries in local or global
|
|
configuration files.
|
|
|
|
## LOCAL GIT REPOS
|
|
|
|
Bundler also allows you to work against a git repository locally
|
|
instead of using the remote version. This can be achieved by setting
|
|
up a local override:
|
|
|
|
bundle config local.GEM_NAME /path/to/local/git/repository
|
|
|
|
For example, in order to use a local Rack repository, a developer could call:
|
|
|
|
bundle config local.rack ~/Work/git/rack
|
|
|
|
Now instead of checking out the remote git repository, the local
|
|
override will be used. Similar to a path source, every time the local
|
|
git repository change, changes will be automatically picked up by
|
|
Bundler. This means a commit in the local git repo will update the
|
|
revision in the `Gemfile.lock` to the local git repo revision. This
|
|
requires the same attention as git submodules. Before pushing to
|
|
the remote, you need to ensure the local override was pushed, otherwise
|
|
you may point to a commit that only exists in your local machine.
|
|
|
|
Bundler does many checks to ensure a developer won't work with
|
|
invalid references. Particularly, we force a developer to specify
|
|
a branch in the `Gemfile` in order to use this feature. If the branch
|
|
specified in the `Gemfile` and the current branch in the local git
|
|
repository do not match, Bundler will abort. This ensures that
|
|
a developer is always working against the correct branches, and prevents
|
|
accidental locking to a different branch.
|
|
|
|
Finally, Bundler also ensures that the current revision in the
|
|
`Gemfile.lock` exists in the local git repository. By doing this, Bundler
|
|
forces you to fetch the latest changes in the remotes.
|
|
|
|
## MIRRORS OF GEM REPOSITORIES
|
|
|
|
Bundler supports overriding gem sources with mirrors. This allows you to
|
|
configure rubygems.org as the gem source in your Gemfile while still using your
|
|
mirror to fetch gems.
|
|
|
|
bundle config mirror.http://rubygems.org http://rubygems-mirror.org
|
|
|