bundler 1.9.0 → 1.17.3

data/man/bundle-config.1.txt

@@ -0,0 +1,529 @@
+BUNDLE-CONFIG(1)					      BUNDLE-CONFIG(1)
+
+
+
+NAME
+       bundle-config - Set bundler configuration options
+
+SYNOPSIS
+       bundle config [name [value]]
+
+DESCRIPTION
+       This  command  allows you to interact with Bundler's configuration sys-
+       tem.
+
+       Bundler loads configuration settings in this order:
+
+       1.  Local config (app/.bundle/config)
+
+       2.  Environmental variables (ENV)
+
+       3.  Global config (~/.bundle/config)
+
+       4.  Bundler default config
+
+
+
+       Executing bundle config with no parameters will print  a  list  of  all
+       bundler configuration for the current bundle, and where that configura-
+       tion was set.
+
+       Executing bundle config <name> will print the value of that  configura-
+       tion 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 configura-
+       tion 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.
+
+       Executing bundle config disable_multisource true upgrades  the  warning
+       about the Gemfile containing multiple primary sources to an error. Exe-
+       cuting bundle config --delete 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 not remembered	between  commands.  If
+       these  options  must be remembered,they must be set using bundle config
+       (e.g., bundle config path foo).
+
+       The options that can be configured are:
+
+       bin    Creates a directory (defaults to ~/bin) and place  any  executa-
+	      bles from the gem there. These executables run in Bundler's con-
+	      text. If used, you might add this  directory  to	your  environ-
+	      ment'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  pro-
+	      duction  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 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) bun-
+       dle-install.1.html prevents  Bundler  from  installing  certain	groups
+       specified  in  the Gemfile(5). Bundler persists this value in app/.bun-
+       dle/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 BUN-
+       DLE_WITHOUT.
+
+       Any periods in the configuration keys must be replaced with two	under-
+       scores 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) bun-
+       dle-install.1.html.
+
+       o   allow_bundler_dependency_conflicts	  (BUNDLE_ALLOW_BUNDLER_DEPEN-
+	   DENCY_CONFLICTS):  Allow  resolving	to  specifications  that  have
+	   dependencies on bundler that  are  incompatible  with  the  running
+	   Bundler version.
+
+       o   allow_deployment_source_credential_changes	 (BUNDLE_ALLOW_DEPLOY-
+	   MENT_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:pass-
+	   word@some.host.com/gems/path
+
+       o   allow_offline_install (BUNDLE_ALLOW_OFFLINE_INSTALL): Allow Bundler
+	   to use cached data when installing without network access.
+
+       o   auto_clean_without_path (BUNDLE_AUTO_CLEAN_WITHOUT_PATH): Automati-
+	   cally  run  bundle clean after installing when an explicit path has
+	   not been set and Bundler is not installing into the system gems.
+
+       o   auto_install  (BUNDLE_AUTO_INSTALL):   Automatically   run	bundle
+	   install when gems are missing.
+
+       o   bin	(BUNDLE_BIN):  Install	executables from gems in the bundle to
+	   the specified directory. Defaults to false.
+
+       o   cache_all (BUNDLE_CACHE_ALL): Cache all gems,  including  path  and
+	   git gems.
+
+       o   cache_all_platforms	(BUNDLE_CACHE_ALL_PLATFORMS):  Cache  gems for
+	   all platforms.
+
+       o   cache_path (BUNDLE_CACHE_PATH): The	directory  that  bundler  will
+	   place  cached gems in when running bundle package, and that bundler
+	   will look in when installing gems. Defaults to vendor/bundle.
+
+       o   clean (BUNDLE_CLEAN): Whether Bundler should run bundle clean auto-
+	   matically after bundle install.
+
+       o   console  (BUNDLE_CONSOLE):  The console that bundle console starts.
+	   Defaults to irb.
+
+       o   default_install_uses_path	   (BUNDLE_DEFAULT_INSTALL_USES_PATH):
+	   Whether  a  bundle  install	without  an  explicit  --path argument
+	   defaults to installing gems in .bundle.
+
+       o   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.
+
+       o   disable_checksum_validation	 (BUNDLE_DISABLE_CHECKSUM_VALIDATION):
+	   Allow  installing  gems even if they do not match the checksum pro-
+	   vided by RubyGems.
+
+       o   disable_exec_load  (BUNDLE_DISABLE_EXEC_LOAD):  Stop  Bundler  from
+	   using load to launch an executable in-process in bundle exec.
+
+       o   disable_local_branch_check	  (BUNDLE_DISABLE_LOCAL_BRANCH_CHECK):
+	   Allow Bundler to use a local git override without a	branch	speci-
+	   fied in the Gemfile.
+
+       o   disable_multisource	(BUNDLE_DISABLE_MULTISOURCE):  When  set, Gem-
+	   files containing multiple sources will produce  errors  instead  of
+	   warnings.  Use bundle config --delete disable_multisource to unset.
+
+       o   disable_platform_warnings (BUNDLE_DISABLE_PLATFORM_WARNINGS):  Dis-
+	   able  warnings during bundle install when a dependency is unused on
+	   the current platform.
+
+       o   disable_shared_gems (BUNDLE_DISABLE_SHARED_GEMS): Stop Bundler from
+	   accessing gems installed to RubyGems' normal location.
+
+       o   disable_version_check  (BUNDLE_DISABLE_VERSION_CHECK): Stop Bundler
+	   from  checking  if  a  newer  Bundler  version  is	available   on
+	   rubygems.org.
+
+       o   error_on_stderr  (BUNDLE_ERROR_ON_STDERR):  Print Bundler errors to
+	   stderr.
+
+       o   force_ruby_platform (BUNDLE_FORCE_RUBY_PLATFORM): Ignore  the  cur-
+	   rent  machine's  platform and install only ruby platform gems. As a
+	   result, gems with native extensions will be compiled from source.
+
+       o   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  --deploy-
+	   ment is used.
+
+       o   gem.push_key  (BUNDLE_GEM__PUSH_KEY):  Sets the --key parameter for
+	   gem push when using the rake release command with  a  private  gem-
+	   stash server.
+
+       o   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 Gem-
+	   file, among other things. By default, bundler will search  up  from
+	   the current working directory until it finds a Gemfile.
+
+       o   global_gem_cache  (BUNDLE_GLOBAL_GEM_CACHE): Whether Bundler should
+	   cache all gems globally, rather than locally to the installing Ruby
+	   installation.
+
+       o   global_path_appends_ruby_scope				 (BUN-
+	   DLE_GLOBAL_PATH_APPENDS_RUBY_SCOPE): Whether Bundler should	append
+	   the	Ruby scope (e.g. engine and ABI version) to a globally-config-
+	   ured path.
+
+       o   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.
+
+       o   init_gems_rb (BUNDLE_INIT_GEMS_RB) Generate a gems.rb instead of  a
+	   Gemfile when running bundle init.
+
+       o   jobs  (BUNDLE_JOBS): The number of gems Bundler can install in par-
+	   allel. Defaults to 1.
+
+       o   list_command (BUNDLE_LIST_COMMAND) Enable new list command feature
+
+       o   major_deprecations  (BUNDLE_MAJOR_DEPRECATIONS):  Whether   Bundler
+	   should print deprecation warnings for behavior that will be changed
+	   in the next major version.
+
+       o   no_install (BUNDLE_NO_INSTALL): Whether bundle package should  skip
+	   installing gems.
+
+       o   no_prune  (BUNDLE_NO_PRUNE):  Whether Bundler should leave outdated
+	   gems unpruned when caching.
+
+       o   only_update_to_newer_versions     (BUNDLE_ONLY_UPDATE_TO_NEWER_VER-
+	   SIONS): During bundle update, only resolve to newer versions of the
+	   gems in the lockfile.
+
+       o   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.
+
+       o   path.system (BUNDLE_PATH__SYSTEM):  Whether	Bundler  will  install
+	   gems into the default system path (Gem.dir).
+
+       o   path_relative_to_cwd  (PATH_RELATIVE_TO_CWD)  Makes --path relative
+	   to the CWD instead of the Gemfile.
+
+       o   plugins (BUNDLE_PLUGINS): Enable Bundler's experimental plugin sys-
+	   tem.
+
+       o   prefer_gems_rb  (BUNDLE_PREFER_GEMS_RB)  Prefer  gems.rb to Gemfile
+	   when Bundler is searching for a Gemfile.
+
+       o   print_only_version_number (BUNDLE_PRINT_ONLY_VERSION_NUMBER)  Print
+	   only version number from bundler --version.
+
+       o   redirect  (BUNDLE_REDIRECT):  The  number  of redirects allowed for
+	   network requests. Defaults to 5.
+
+       o   retry (BUNDLE_RETRY): The number of times to retry  failed  network
+	   requests. Defaults to 3.
+
+       o   setup_makes_kernel_gem_public   (BUNDLE_SETUP_MAKES_KERNEL_GEM_PUB-
+	   LIC): Have Bundler.setup make the Kernel#gem  method  public,  even
+	   though RubyGems declares it as private.
+
+       o   shebang  (BUNDLE_SHEBANG):  The program name that should be invoked
+	   for generated binstubs. Defaults to the ruby install name  used  to
+	   generate the binstub.
+
+       o   silence_root_warning   (BUNDLE_SILENCE_ROOT_WARNING):  Silence  the
+	   warning Bundler prints when installing gems as root.
+
+       o   skip_default_git_sources (BUNDLE_SKIP_DEFAULT_GIT_SOURCES): Whether
+	   Bundler should skip adding default git source shortcuts to the Gem-
+	   file DSL.
+
+       o   specific_platform  (BUNDLE_SPECIFIC_PLATFORM):  Allow  bundler   to
+	   resolve for the specific running platform and store it in the lock-
+	   file, 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.
+
+       o   ssl_ca_cert	(BUNDLE_SSL_CA_CERT): Path to a designated CA certifi-
+	   cate file or folder containing multiple  certificates  for  trusted
+	   CAs in PEM format.
+
+       o   ssl_client_cert (BUNDLE_SSL_CLIENT_CERT): Path to a designated file
+	   containing a X.509 client certificate and key in PEM format.
+
+       o   ssl_verify_mode (BUNDLE_SSL_VERIFY_MODE): The SSL verification mode
+	   Bundler uses when making HTTPS requests. Defaults to verify peer.
+
+       o   suppress_install_using_messages (BUNDLE_SUPPRESS_INSTALL_USING_MES-
+	   SAGES): Avoid printing Using ... messages during installation  when
+	   the version of a gem has not changed.
+
+       o   system_bindir  (BUNDLE_SYSTEM_BINDIR):  The location where RubyGems
+	   installs binstubs. Defaults to Gem.bindir.
+
+       o   timeout (BUNDLE_TIMEOUT): The seconds allowed before timing out for
+	   network requests. Defaults to 10.
+
+       o   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.
+
+       o   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.
+
+       o   user_agent  (BUNDLE_USER_AGENT):  The  custom  user	agent fragment
+	   Bundler includes in API requests.
+
+       o   with (BUNDLE_WITH): A :-separated list of groups whose gems bundler
+	   should install.
+
+       o   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 bun-
+       dle 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, envi-
+       ronment 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 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 over-
+       ride 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 com-
+       mit 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 Gem-
+       file.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 mirror.SOURCE_URL MIRROR_URL
+
+
+
+       For  example,  to  use a mirror of rubygems.org hosted at rubygems-mir-
+       ror.org:
+
+
+
+	   bundle config 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 mirror.SOURCE_URL.fallback_timeout TIMEOUT
+
+
+
+       For example, to fall back to rubygems.org after 3 seconds:
+
+
+
+	   bundle config mirror.https://rubygems.org.fallback_timeout 3
+
+
+
+       The default fallback timeout is 0.1 seconds, but the setting  can  cur-
+       rently 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 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 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 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 vari-
+       ables 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
+
+
+
+
+
+
+				 December 2018		      BUNDLE-CONFIG(1)