bundler 1.15.4 → 1.16.0.pre.1

data/man/bundle-config.1.txt

@@ -0,0 +1,491 @@
+BUNDLE-CONFIG(1)					      BUNDLE-CONFIG(1)
+
+
+
+1mNAME0m
+       1mbundle-config 22m- Set bundler configuration options
+
+1mSYNOPSIS0m
+       1mbundle config 22m[4mname24m [4mvalue24m]]
+
+1mDESCRIPTION0m
+       This  command  allows you to interact with bundler's configuration sys-
+       tem. Bundler retrieves its configuration  from  the  local  application
+       (1mapp/.bundle/config22m), environment variables, and the user's home direc-
+       tory (1m~/.bundle/config22m), in that order of priority.
+
+       Executing 1mbundle config 22mwith no parameters will print  a  list  of	all
+       bundler configuration for the current bundle, and where that configura-
+       tion was set.
+
+       Executing 1mbundle config <name> 22mwill print the value of that  configura-
+       tion setting, and where it was set.
+
+       Executing  1mbundle  config <name> <value> 22mwill set that configuration to
+       the value specified for all bundles executed as the current  user.  The
+       configuration  will  be	stored in 1m~/.bundle/config22m. If 4mname24m already is
+       set, 4mname24m will be overridden and user will be warned.
+
+       Executing 1mbundle config --global  <name>  <value>  22mworks  the  same  as
+       above.
+
+       Executing 1mbundle config --local <name> <value> 22mwill set that configura-
+       tion to the local application. The  configuration  will	be  stored  in
+       1mapp/.bundle/config22m.
+
+       Executing  1mbundle  config --delete <name> 22mwill delete the configuration
+       in both local and global  sources.  Not	compatible  with  --global  or
+       --local flag.
+
+       Executing bundle with the 1mBUNDLE_IGNORE_CONFIG 22menvironment variable set
+       will cause it to ignore all configuration.
+
+       Executing 1mbundle config disable_multisource true 22mupgrades  the  warning
+       about the Gemfile containing multiple primary sources to an error. Exe-
+       cuting 1mbundle config --delete disable_multisource 22mdowngrades this error
+       to a warning.
+
+1mREMEMBERING OPTIONS0m
+       Flags  passed  to 1mbundle install 22mor the Bundler runtime, such as 1m--path0m
+       1mfoo 22mor 1m--without production22m, are not remembered  between  commands.  If
+       these  options  must be remembered,they must be set using 1mbundle config0m
+       (e.g., 1mbundle config path foo22m).
+
+       The options that can be configured are:
+
+       1mbin	22mCreates a directory (defaults to 1m~/bin22m) 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  1mPATH 22mvariable. For instance, if the 1mrails 22mgem comes with
+	      a 1mrails 22mexecutable, this flag will create a 1mbin/rails 22mexecutable
+	      that  ensures  that  all	referred dependencies will be resolved
+	      using the bundled gems.
+
+       1mdeployment0m
+	      In deployment mode, Bundler will 'roll-out' the bundle for  1mpro-0m
+	      1mduction  22muse.  Please  check  carefully if you want to have this
+	      option enabled in 1mdevelopment 22mor 1mtest 22menvironments.
+
+       1mpath	22mThe location to install the specified gems to. This defaults  to
+	      Rubygems'  setting.  Bundler shares this location with Rubygems,
+	      1mgem install ... 22mwill have gem installed there,  too.  Therefore,
+	      gems  installed  without	a  1m--path  ... 22msetting will show up by
+	      calling 1mgem list22m. Accordingly, gems installed to other locations
+	      will not get listed.
+
+       1mwithout0m
+	      A space-separated list of groups referencing gems to skip during
+	      installation.
+
+       1mwith	22mA space-separated list of groups  referencing  gems	to  include
+	      during installation.
+
+1mBUILD OPTIONS0m
+       You  can use 1mbundle config 22mto give bundler the flags to pass to the gem
+       installer every time bundler tries to install a particular gem.
+
+       A very common example, the 1mmysql 22mgem, requires Snow  Leopard  users  to
+       pass  configuration  flags  to 1mgem install 22mto specify where to find the
+       1mmysql_config 22mexecutable.
+
+
+
+	   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
+       1mmysql 22mgem, it will pass along the flags you specified.
+
+1mCONFIGURATION KEYS0m
+       Configuration keys in bundler have two forms: the  canonical  form  and
+       the environment variable form.
+
+       For  instance,  passing	the 1m--without 22mflag to [bundle install(1)][bun-
+       dle-install] prevents Bundler from installing certain groups  specified
+       in the Gemfile(5). Bundler persists this value in 1mapp/.bundle/config 22mso
+       that calls to 1mBundler.setup 22mdo not try to find gems  from  the  1mGemfile0m
+       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 1m"without"22m. To convert the
+       canonical form to the environment variable  form,  capitalize  it,  and
+       prepend	1mBUNDLE_22m.  The  environment  variable form of 1m"without" 22mis 1mBUN-0m
+       1mDLE_WITHOUT22m.
+
+       Any periods in the configuration keys must be replaced with two	under-
+       scores when setting it via environment variables. The configuration key
+       1mlocal.rack 22mbecomes the environment variable 1mBUNDLE_LOCAL__RACK22m.
+
+1mLIST OF AVAILABLE KEYS0m
+       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].
+
+       o   1mallow_bundler_dependency_conflicts     22m(1mBUNDLE_ALLOW_BUNDLER_DEPEN-0m
+	   1mDENCY_CONFLICTS22m):  Allow  resolving  to  specifications  that  have
+	   dependencies on 1mbundler 22mthat  are  incompatible  with  the  running
+	   Bundler version.
+
+       o   1mallow_deployment_source_credential_changes    22m(1mBUNDLE_ALLOW_DEPLOY-0m
+	   1mMENT_SOURCE_CREDENTIAL_CHANGES22m): When  in  deployment  mode,  allow
+	   changing    the    credentials    to    a	gem's	 source.   Ex:
+	   1mhttps://some.host.com/gems/path/	  22m->     1mhttps://user_name:pass-0m
+	   1mword@some.host.com/gems/path0m
+
+       o   1mallow_offline_install 22m(1mBUNDLE_ALLOW_OFFLINE_INSTALL22m): Allow Bundler
+	   to use cached data when installing without network access.
+
+       o   1mauto_clean_without_path 22m(1mBUNDLE_AUTO_CLEAN_WITHOUT_PATH22m): Automati-
+	   cally  run  1mbundle clean 22mafter installing when an explicit 1mpath 22mhas
+	   not been set and Bundler is not installing into the system gems.
+
+       o   1mauto_install  22m(1mBUNDLE_AUTO_INSTALL22m):   Automatically   run   1mbundle0m
+	   1minstall 22mwhen gems are missing.
+
+       o   1mbin  22m(1mBUNDLE_BIN22m):  Install  executables from gems in the bundle to
+	   the specified directory. Defaults to 1mfalse22m.
+
+       o   1mcache_all 22m(1mBUNDLE_CACHE_ALL22m): Cache all gems,  including  path  and
+	   git gems.
+
+       o   1mcache_all_platforms  22m(1mBUNDLE_CACHE_ALL_PLATFORMS22m):  Cache	gems for
+	   all platforms.
+
+       o   1mcache_path 22m(1mBUNDLE_CACHE_PATH22m): The  directory  that  bundler  will
+	   place  cached gems in when running 1mbundle package22m, and that bundler
+	   will look in when installing gems. Defaults to 1mvendor/bundle22m.
+
+       o   1mclean 22m(1mBUNDLE_CLEAN22m): Whether Bundler should run 1mbundle clean 22mauto-
+	   matically after 1mbundle install22m.
+
+       o   1mconsole  22m(1mBUNDLE_CONSOLE22m):  The console that 1mbundle console 22mstarts.
+	   Defaults to 1mirb22m.
+
+       o   1mdefault_install_uses_path	     22m(1mBUNDLE_DEFAULT_INSTALL_USES_PATH22m):
+	   Whether  a  1mbundle  install  22mwithout  an  explicit  1m--path 22margument
+	   defaults to installing gems in 1m.bundle22m.
+
+       o   1mdeployment 22m(1mBUNDLE_DEPLOYMENT22m): Disallow changes  to  the	1mGemfile22m.
+	   When  the 1mGemfile 22mis changed and the lockfile has not been updated,
+	   running Bundler commands will be blocked.
+
+       o   1mdisable_checksum_validation   22m(1mBUNDLE_DISABLE_CHECKSUM_VALIDATION22m):
+	   Allow  installing  gems even if they do not match the checksum pro-
+	   vided by RubyGems.
+
+       o   1mdisable_exec_load	22m(1mBUNDLE_DISABLE_EXEC_LOAD22m):  Stop  Bundler  from
+	   using 1mload 22mto launch an executable in-process in 1mbundle exec22m.
+
+       o   1mdisable_local_branch_check     22m(1mBUNDLE_DISABLE_LOCAL_BRANCH_CHECK22m):
+	   Allow Bundler to use a local git override without a	branch	speci-
+	   fied in the Gemfile.
+
+       o   1mdisable_multisource  22m(1mBUNDLE_DISABLE_MULTISOURCE22m):  When  set, Gem-
+	   files containing multiple sources will produce  errors  instead  of
+	   warnings. Use 1mbundle config --delete disable_multisource 22mto unset.
+
+       o   1mdisable_shared_gems 22m(1mBUNDLE_DISABLE_SHARED_GEMS22m): Stop Bundler from
+	   accessing gems installed to RubyGems' normal location.
+
+       o   1mdisable_version_check 22m(1mBUNDLE_DISABLE_VERSION_CHECK22m): Stop  Bundler
+	   from   checking   if  a  newer  Bundler  version  is  available  on
+	   rubygems.org.
+
+       o   1merror_on_stderr 22m(1mBUNDLE_ERROR_ON_STDERR22m): Print Bundler  errors  to
+	   stderr.
+
+       o   1mforce_ruby_platform  22m(1mBUNDLE_FORCE_RUBY_PLATFORM22m):  Ignore the cur-
+	   rent machine's platform and install only 1mruby 22mplatform gems.  As  a
+	   result, gems with native extensions will be compiled from source.
+
+       o   1mfrozen  22m(1mBUNDLE_FROZEN22m):  Disallow changes to the 1mGemfile22m. When the
+	   1mGemfile 22mis changed and the lockfile has not been  updated,  running
+	   Bundler  commands  will be blocked. Defaults to 1mtrue 22mwhen 1m--deploy-0m
+	   1mment 22mis used.
+
+       o   1mgem.push_key 22m(1mBUNDLE_GEM__PUSH_KEY22m): Sets the 1m--key  22mparameter  for
+	   1mgem  push	22mwhen  using the 1mrake release 22mcommand with a private gem-
+	   stash server.
+
+       o   1mgemfile 22m(1mBUNDLE_GEMFILE22m): The name of the file that bundler  should
+	   use	as  the 1mGemfile22m. This location of this file also sets the root
+	   of the project, which is used to resolve relative paths in the 1mGem-0m
+	   1mfile22m,  among  other things. By default, bundler will search up from
+	   the current working directory until it finds a 1mGemfile22m.
+
+       o   1mglobal_gem_cache 22m(1mBUNDLE_GLOBAL_GEM_CACHE22m): Whether Bundler  should
+	   cache all gems globally, rather than locally to the installing Ruby
+	   installation.
+
+       o   1mignore_messages 22m(1mBUNDLE_IGNORE_MESSAGES22m): When set, no post install
+	   messages will be printed. To silence a single gem, use dot notation
+	   like 1mignore_messages.httparty true22m.
+
+       o   1minit_gems_rb 22m(1mBUNDLE_INIT_GEMS_RB22m) Generate a 1mgems.rb 22minstead of  a
+	   1mGemfile 22mwhen running 1mbundle init22m.
+
+       o   1mjobs  22m(1mBUNDLE_JOBS22m): The number of gems Bundler can install in par-
+	   allel. Defaults to 1.
+
+       o   1mlist_command 22m(1mBUNDLE_LIST_COMMAND22m) Enable new list command feature
+
+       o   1mmajor_deprecations  22m(1mBUNDLE_MAJOR_DEPRECATIONS22m):  Whether	 Bundler
+	   should print deprecation warnings for behavior that will be changed
+	   in the next major version.
+
+       o   1mno_install 22m(1mBUNDLE_NO_INSTALL22m): Whether 1mbundle package 22mshould  skip
+	   installing gems.
+
+       o   1mno_prune  22m(1mBUNDLE_NO_PRUNE22m):  Whether Bundler should leave outdated
+	   gems unpruned when caching.
+
+       o   1monly_update_to_newer_versions     22m(1mBUNDLE_ONLY_UPDATE_TO_NEWER_VER-0m
+	   1mSIONS22m): During 1mbundle update22m, only resolve to newer versions of the
+	   gems in the lockfile.
+
+       o   1mpath 22m(1mBUNDLE_PATH22m): The location on disk where  all  gems	in  your
+	   bundle will be located regardless of 1m$GEM_HOME 22mor 1m$GEM_PATH 22mvalues.
+	   Bundle gems not found in this location will be installed by	1mbundle0m
+	   1minstall22m.  Defaults  to 1mGem.dir22m. When --deployment is used, defaults
+	   to vendor/bundle.
+
+       o   1mpath.system 22m(1mBUNDLE_PATH__SYSTEM22m):  Whether  Bundler  will  install
+	   gems into the default system path (1mGem.dir22m).
+
+       o   1mplugins 22m(1mBUNDLE_PLUGINS22m): Enable Bundler's experimental plugin sys-
+	   tem.
+
+       o   1mprefer_gems_rb 22m(1mBUNDLE_PREFER_GEMS_RB22m) Prefer  1mgems.rb  22mto  1mGemfile0m
+	   when Bundler is searching for a Gemfile.
+
+       o   1mprint_only_version_number	22m(1mBUNDLE_PRINT_ONLY_VERSION_NUMBER22m) Print
+	   only version number from 1mbundler --version22m.
+
+       o   1mredirect 22m(1mBUNDLE_REDIRECT22m): The number  of  redirects  allowed  for
+	   network requests. Defaults to 1m522m.
+
+       o   1mretry  22m(1mBUNDLE_RETRY22m):  The number of times to retry failed network
+	   requests. Defaults to 1m322m.
+
+       o   1msetup_makes_kernel_gem_public   22m(1mBUNDLE_SETUP_MAKES_KERNEL_GEM_PUB-0m
+	   1mLIC22m):  Have  1mBundler.setup  22mmake the 1mKernel#gem 22mmethod public, even
+	   though RubyGems declares it as private.
+
+       o   1mshebang 22m(1mBUNDLE_SHEBANG22m): The program name that should  be  invoked
+	   for	generated  binstubs. Defaults to the ruby install name used to
+	   generate the binstub.
+
+       o   1msilence_root_warning  22m(1mBUNDLE_SILENCE_ROOT_WARNING22m):  Silence   the
+	   warning Bundler prints when installing gems as root.
+
+       o   1mskip_default_git_sources 22m(1mBUNDLE_SKIP_DEFAULT_GIT_SOURCES22m): Whether
+	   Bundler should skip adding default git source shortcuts to the Gem-
+	   file DSL.
+
+       o   1mspecific_platform	 22m(1mBUNDLE_SPECIFIC_PLATFORM22m):  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 1mGem::Platform.local22m,  such
+	   as  1mx86_64-darwin-16  22mor  1muniversal-java-1.822m.  On	the  other hand,
+	   generic platforms are those such as 1mruby22m, 1mmswin22m, or 1mjava22m.  In  this
+	   example,  1mx86_64-darwin-16 22mwould map to 1mruby 22mand 1muniversal-java-1.80m
+	   to 1mjava22m.
+
+       o   1mssl_ca_cert 22m(1mBUNDLE_SSL_CA_CERT22m): Path to a designated CA	certifi-
+	   cate  file  or  folder containing multiple certificates for trusted
+	   CAs in PEM format.
+
+       o   1mssl_client_cert 22m(1mBUNDLE_SSL_CLIENT_CERT22m): Path to a designated file
+	   containing a X.509 client certificate and key in PEM format.
+
+       o   1mssl_verify_mode 22m(1mBUNDLE_SSL_VERIFY_MODE22m): The SSL verification mode
+	   Bundler uses when making HTTPS requests. Defaults to verify peer.
+
+       o   1msuppress_install_using_messages 22m(1mBUNDLE_SUPPRESS_INSTALL_USING_MES-0m
+	   1mSAGES22m):  Avoid printing 1mUsing ... 22mmessages during installation when
+	   the version of a gem has not changed.
+
+       o   1msystem_bindir 22m(1mBUNDLE_SYSTEM_BINDIR22m): The location  where	RubyGems
+	   installs binstubs. Defaults to 1mGem.bindir22m.
+
+       o   1mtimeout 22m(1mBUNDLE_TIMEOUT22m): The seconds allowed before timing out for
+	   network requests. Defaults to 1m1022m.
+
+       o   1munlock_source_unlocks_spec     22m(1mBUNDLE_UNLOCK_SOURCE_UNLOCKS_SPEC22m):
+	   Whether  running 1mbundle update --source NAME 22munlocks a gem with the
+	   given name. Defaults to 1mtrue22m.
+
+       o   1mupdate_requires_all_flag 22m(1mBUNDLE_UPDATE_REQUIRES_ALL_FLAG22m)  Require
+	   passing  1m--all  22mto 1mbundle update 22mwhen everything should be updated,
+	   and disallow passing no options to 1mbundle update22m.
+
+       o   1muser_agent 22m(1mBUNDLE_USER_AGENT22m):  The  custom  user  agent	fragment
+	   Bundler includes in API requests.
+
+       o   1mwith 22m(1mBUNDLE_WITH22m): A 1m:22m-separated list of groups whose gems bundler
+	   should install.
+
+       o   1mwithout 22m(1mBUNDLE_WITHOUT22m): A 1m:22m-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]  or  [bundle
+       package(1)][bundle-package] command.
+
+       You  can  set  them globally either via environment variables or 1mbundle0m
+       1mconfig22m, whichever is preferable for your setup. If you use both,  envi-
+       ronment variables will take preference over global settings.
+
+1mLOCAL GIT REPOS0m
+       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 1mGemfile.lock 22mto 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 1mGemfile 22min order to use this feature. If the  branch  specified  in
+       the  1mGemfile  22mand 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  1mGem-0m
+       1mfile.lock  22mexists  in  the local git repository. By doing this, Bundler
+       forces you to fetch the latest changes in the remotes.
+
+1mMIRRORS OF GEM SOURCES0m
+       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).
+
+1mCREDENTIALS FOR GEM SOURCES0m
+       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 1mclaudette 22mfor the gem
+       source at 1mgems.longerous.com22m, 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
+
+
+
+
+
+
+				  August 2017		      BUNDLE-CONFIG(1)