diff options
Diffstat (limited to 'man/bundle-config.1.ronn')
| -rw-r--r-- | man/bundle-config.1.ronn | 396 |
1 files changed, 0 insertions, 396 deletions
diff --git a/man/bundle-config.1.ronn b/man/bundle-config.1.ronn deleted file mode 100644 index a0ff30cb15..0000000000 --- a/man/bundle-config.1.ronn +++ /dev/null @@ -1,396 +0,0 @@ -bundle-config(1) -- Set bundler configuration options -===================================================== - -## SYNOPSIS - -`bundle config` [list|get|set|unset] [<name> [<value>]] - -## DESCRIPTION - -This command allows you to interact with Bundler's configuration system. - -Bundler loads configuration settings in this order: - -1. Local config (`<project_root>/.bundle/config` or `$BUNDLE_APP_CONFIG/config`) -2. Environmental variables (`ENV`) -3. Global config (`~/.bundle/config`) -4. Bundler default config - -Executing `bundle config list` with will print a list of all bundler -configuration for the current bundle, and where that configuration -was set. - -Executing `bundle config get <name>` will print the value of that configuration -setting, and where it was set. - -Executing `bundle config set <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 set --global <name> <value>` works the same as above. - -Executing `bundle config set --local <name> <value>` will set that configuration -in the directory for the local application. The configuration will be stored in -`<project_root>/.bundle/config`. If `BUNDLE_APP_CONFIG` is set, the configuration -will be stored in `$BUNDLE_APP_CONFIG/config`. - -Executing `bundle config unset <name>` will delete the configuration in both -local and global sources. - -Executing `bundle config unset --global <name>` will delete the configuration -only from the user configuration. - -Executing `bundle config unset --local <name> <value>` will delete the -configuration only from the local application. - -Executing bundle with the `BUNDLE_IGNORE_CONFIG` environment variable set will -cause it to ignore all configuration. - -Executing `bundle config set --local disable_multisource true` upgrades the warning about -the Gemfile containing multiple primary sources to an error. Executing `bundle -config unset disable_multisource` downgrades this error to a warning. - -## REMEMBERING OPTIONS - -Flags passed to `bundle install` or the Bundler runtime, such as `--path foo` or -`--without production`, are remembered between commands and saved to your local -application's configuration (normally, `./.bundle/config`). - -However, this will be changed in bundler 3, so it's better not to rely on this -behavior. If these options must be remembered, it's better to set them using -`bundle config` (e.g., `bundle config set --local path foo`). - -The options that can be configured are: - -* `bin`: - Creates a directory (defaults to `~/bin`) and place any executables from the - gem there. These executables run in Bundler's context. If used, you might add - this directory to your environment's `PATH` variable. For instance, if the - `rails` gem comes with a `rails` executable, this flag will create a - `bin/rails` executable that ensures that all referred dependencies will be - resolved using the bundled gems. - -* `deployment`: - In deployment mode, Bundler will 'roll-out' the bundle for - `production` use. Please check carefully if you want to have this option - enabled in `development` or `test` environments. - -* `path`: - The location to install the specified gems to. This defaults to Rubygems' - setting. Bundler shares this location with Rubygems, `gem install ...` will - have gem installed there, too. Therefore, gems installed without a - `--path ...` setting will show up by calling `gem list`. Accordingly, gems - installed to other locations will not get listed. - -* `without`: - A space-separated list of groups referencing gems to skip during installation. - -* `with`: - A space-separated list of groups referencing gems to include during installation. - -## 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 set --global 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.1.html) -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.1.html) 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`. - -Any periods in the configuration keys must be replaced with two underscores when -setting it via environment variables. The configuration key `local.rack` becomes -the environment variable `BUNDLE_LOCAL__RACK`. - -## 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.1.html). - -* `allow_bundler_dependency_conflicts` (`BUNDLE_ALLOW_BUNDLER_DEPENDENCY_CONFLICTS`): - Allow resolving to specifications that have dependencies on `bundler` that - are incompatible with the running Bundler version. -* `allow_deployment_source_credential_changes` (`BUNDLE_ALLOW_DEPLOYMENT_SOURCE_CREDENTIAL_CHANGES`): - When in deployment mode, allow changing the credentials to a gem's source. - Ex: `https://some.host.com/gems/path/` -> `https://user_name:password@some.host.com/gems/path` -* `allow_offline_install` (`BUNDLE_ALLOW_OFFLINE_INSTALL`): - Allow Bundler to use cached data when installing without network access. -* `auto_clean_without_path` (`BUNDLE_AUTO_CLEAN_WITHOUT_PATH`): - Automatically run `bundle clean` after installing when an explicit `path` - has not been set and Bundler is not installing into the system gems. -* `auto_install` (`BUNDLE_AUTO_INSTALL`): - Automatically run `bundle install` when gems are missing. -* `bin` (`BUNDLE_BIN`): - Install executables from gems in the bundle to the specified directory. - Defaults to `false`. -* `cache_all` (`BUNDLE_CACHE_ALL`): - Cache all gems, including path and git gems. This needs to be explicitly - configured on bundler 1 and bundler 2, but will be the default on bundler 3. -* `cache_all_platforms` (`BUNDLE_CACHE_ALL_PLATFORMS`): - Cache gems for all platforms. -* `cache_path` (`BUNDLE_CACHE_PATH`): - The directory that bundler will place cached gems in when running - <code>bundle package</code>, and that bundler will look in when installing gems. - Defaults to `vendor/cache`. -* `clean` (`BUNDLE_CLEAN`): - Whether Bundler should run `bundle clean` automatically after - `bundle install`. -* `console` (`BUNDLE_CONSOLE`): - The console that `bundle console` starts. Defaults to `irb`. -* `default_install_uses_path` (`BUNDLE_DEFAULT_INSTALL_USES_PATH`): - Whether a `bundle install` without an explicit `--path` argument defaults - to installing gems in `.bundle`. -* `deployment` (`BUNDLE_DEPLOYMENT`): - Disallow changes to the `Gemfile`. When the `Gemfile` is changed and the - lockfile has not been updated, running Bundler commands will be blocked. -* `disable_checksum_validation` (`BUNDLE_DISABLE_CHECKSUM_VALIDATION`): - Allow installing gems even if they do not match the checksum provided by - RubyGems. -* `disable_exec_load` (`BUNDLE_DISABLE_EXEC_LOAD`): - Stop Bundler from using `load` to launch an executable in-process in - `bundle exec`. -* `disable_local_branch_check` (`BUNDLE_DISABLE_LOCAL_BRANCH_CHECK`): - Allow Bundler to use a local git override without a branch specified in the - Gemfile. -* `disable_multisource` (`BUNDLE_DISABLE_MULTISOURCE`): - When set, Gemfiles containing multiple sources will produce errors - instead of warnings. - Use `bundle config unset disable_multisource` to unset. -* `disable_shared_gems` (`BUNDLE_DISABLE_SHARED_GEMS`): - Stop Bundler from accessing gems installed to RubyGems' normal location. -* `disable_version_check` (`BUNDLE_DISABLE_VERSION_CHECK`): - Stop Bundler from checking if a newer Bundler version is available on - rubygems.org. -* `force_ruby_platform` (`BUNDLE_FORCE_RUBY_PLATFORM`): - Ignore the current machine's platform and install only `ruby` platform gems. - As a result, gems with native extensions will be compiled from source. -* `frozen` (`BUNDLE_FROZEN`): - Disallow changes to the `Gemfile`. When the `Gemfile` is changed and the - lockfile has not been updated, running Bundler commands will be blocked. - Defaults to `true` when `--deployment` is used. -* `gem.push_key` (`BUNDLE_GEM__PUSH_KEY`): - Sets the `--key` parameter for `gem push` when using the `rake release` - command with a private gemstash server. -* `gemfile` (`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`. -* `global_gem_cache` (`BUNDLE_GLOBAL_GEM_CACHE`): - Whether Bundler should cache all gems globally, rather than locally to the - installing Ruby installation. -* `ignore_messages` (`BUNDLE_IGNORE_MESSAGES`): When set, no post install - messages will be printed. To silence a single gem, use dot notation like - `ignore_messages.httparty true`. -* `init_gems_rb` (`BUNDLE_INIT_GEMS_RB`) - Generate a `gems.rb` instead of a `Gemfile` when running `bundle init`. -* `jobs` (`BUNDLE_JOBS`): - The number of gems Bundler can install in parallel. Defaults to 1. -* `no_install` (`BUNDLE_NO_INSTALL`): - Whether `bundle package` should skip installing gems. -* `no_prune` (`BUNDLE_NO_PRUNE`): - Whether Bundler should leave outdated gems unpruned when caching. -* `only_update_to_newer_versions` (`BUNDLE_ONLY_UPDATE_TO_NEWER_VERSIONS`): - During `bundle update`, only resolve to newer versions of the gems in the - lockfile. -* `path` (`BUNDLE_PATH`): - The location on disk where all gems in your bundle will be located regardless - of `$GEM_HOME` or `$GEM_PATH` values. Bundle gems not found in this location - will be installed by `bundle install`. Defaults to `Gem.dir`. When --deployment - is used, defaults to vendor/bundle. -* `path.system` (`BUNDLE_PATH__SYSTEM`): - Whether Bundler will install gems into the default system path (`Gem.dir`). -* `path_relative_to_cwd` (`BUNDLE_PATH_RELATIVE_TO_CWD`) - Makes `--path` relative to the CWD instead of the `Gemfile`. -* `plugins` (`BUNDLE_PLUGINS`): - Enable Bundler's experimental plugin system. -* `prefer_patch` (BUNDLE_PREFER_PATCH): - Prefer updating only to next patch version during updates. Makes `bundle update` calls equivalent to `bundler update --patch`. -* `print_only_version_number` (`BUNDLE_PRINT_ONLY_VERSION_NUMBER`) - Print only version number from `bundler --version`. -* `redirect` (`BUNDLE_REDIRECT`): - The number of redirects allowed for network requests. Defaults to `5`. -* `retry` (`BUNDLE_RETRY`): - The number of times to retry failed network requests. Defaults to `3`. -* `setup_makes_kernel_gem_public` (`BUNDLE_SETUP_MAKES_KERNEL_GEM_PUBLIC`): - Have `Bundler.setup` make the `Kernel#gem` method public, even though - RubyGems declares it as private. -* `shebang` (`BUNDLE_SHEBANG`): - The program name that should be invoked for generated binstubs. Defaults to - the ruby install name used to generate the binstub. -* `silence_deprecations` (`BUNDLE_SILENCE_DEPRECATIONS`): - Whether Bundler should silence deprecation warnings for behavior that will - be changed in the next major version. -* `silence_root_warning` (`BUNDLE_SILENCE_ROOT_WARNING`): - Silence the warning Bundler prints when installing gems as root. -* `specific_platform` (`BUNDLE_SPECIFIC_PLATFORM`): - Allow bundler to resolve for the specific running platform and store it in - the lockfile, instead of only using a generic platform. - A specific platform is the exact platform triple reported by - `Gem::Platform.local`, such as `x86_64-darwin-16` or `universal-java-1.8`. - On the other hand, generic platforms are those such as `ruby`, `mswin`, or - `java`. In this example, `x86_64-darwin-16` would map to `ruby` and - `universal-java-1.8` to `java`. -* `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. -* `ssl_verify_mode` (`BUNDLE_SSL_VERIFY_MODE`): - The SSL verification mode Bundler uses when making HTTPS requests. - Defaults to verify peer. -* `suppress_install_using_messages` (`BUNDLE_SUPPRESS_INSTALL_USING_MESSAGES`): - Avoid printing `Using ...` messages during installation when the version of - a gem has not changed. -* `system_bindir` (`BUNDLE_SYSTEM_BINDIR`): - The location where RubyGems installs binstubs. Defaults to `Gem.bindir`. -* `timeout` (`BUNDLE_TIMEOUT`): - The seconds allowed before timing out for network requests. Defaults to `10`. -* `unlock_source_unlocks_spec` (`BUNDLE_UNLOCK_SOURCE_UNLOCKS_SPEC`): - Whether running `bundle update --source NAME` unlocks a gem with the given - name. Defaults to `true`. -* `update_requires_all_flag` (`BUNDLE_UPDATE_REQUIRES_ALL_FLAG`) - Require passing `--all` to `bundle update` when everything should be updated, - and disallow passing no options to `bundle update`. -* `user_agent` (`BUNDLE_USER_AGENT`): - The custom user agent fragment Bundler includes in API requests. -* `with` (`BUNDLE_WITH`): - A `:`-separated list of groups whose gems bundler should install. -* `without` (`BUNDLE_WITHOUT`): - A `:`-separated list of groups whose gems bundler should not install. - -In general, you should set these settings per-application by using the applicable -flag to the [bundle install(1)](bundle-install.1.html) or [bundle package(1)](bundle-package.1.html) 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. - -## 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 set --local local.GEM_NAME /path/to/local/git/repository - -For example, in order to use a local Rack repository, a developer could call: - - bundle config set --local 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. -You'll also need to CGI escape your usernames and passwords as well. - -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 SOURCES - -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 set --global mirror.SOURCE_URL MIRROR_URL - -For example, to use a mirror of rubygems.org hosted at rubygems-mirror.org: - - bundle config set --global mirror.http://rubygems.org http://rubygems-mirror.org - -Each mirror also provides a fallback timeout setting. If the mirror does not -respond within the fallback timeout, Bundler will try to use the original -server instead of the mirror. - - bundle config set --global mirror.SOURCE_URL.fallback_timeout TIMEOUT - -For example, to fall back to rubygems.org after 3 seconds: - - bundle config set --global mirror.https://rubygems.org.fallback_timeout 3 - -The default fallback timeout is 0.1 seconds, but the setting can currently -only accept whole seconds (for example, 1, 15, or 30). - -## CREDENTIALS FOR GEM SOURCES - -Bundler allows you to configure credentials for any gem source, which allows -you to avoid putting secrets into your Gemfile. - - bundle config set --global SOURCE_HOSTNAME USERNAME:PASSWORD - -For example, to save the credentials of user `claudette` for the gem source at -`gems.longerous.com`, you would run: - - bundle config set --global gems.longerous.com claudette:s00pers3krit - -Or you can set the credentials as an environment variable like this: - - export BUNDLE_GEMS__LONGEROUS__COM="claudette:s00pers3krit" - -For gems with a git source with HTTP(S) URL you can specify credentials like so: - - bundle config set --global https://github.com/bundler/bundler.git username:password - -Or you can set the credentials as an environment variable like so: - - export BUNDLE_GITHUB__COM=username:password - -This is especially useful for private repositories on hosts such as Github, -where you can use personal OAuth tokens: - - export BUNDLE_GITHUB__COM=abcd0123generatedtoken:x-oauth-basic - - -## CONFIGURE BUNDLER DIRECTORIES - -Bundler's home, config, cache and plugin directories are able to be configured -through environment variables. The default location for Bundler's home directory is -`~/.bundle`, which all directories inherit from by default. The following -outlines the available environment variables and their default values - - BUNDLE_USER_HOME : $HOME/.bundle - BUNDLE_USER_CACHE : $BUNDLE_USER_HOME/cache - BUNDLE_USER_CONFIG : $BUNDLE_USER_HOME/config - BUNDLE_USER_PLUGIN : $BUNDLE_USER_HOME/plugin |