summaryrefslogtreecommitdiff
path: root/man/bundle-config.1.txt
diff options
context:
space:
mode:
authorhsbt <hsbt@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2018-11-02 23:07:56 +0000
committerhsbt <hsbt@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2018-11-02 23:07:56 +0000
commit59c8d50653480bef3f24517296e6ddf937fdf6bc (patch)
treedf10aaf4f3307837fe3d1d129d66f6c0c7586bc5 /man/bundle-config.1.txt
parent7deb37777a230837e865e0a11fb8d7c1dc6d03ce (diff)
Added bundler as default gems. Revisit [Feature #12733]
* bin/*, lib/bundler/*, lib/bundler.rb, spec/bundler, man/*: Merge from latest stable branch of bundler/bundler repository and added workaround patches. I will backport them into upstream. * common.mk, defs/gmake.mk: Added `test-bundler` task for test suite of bundler. * tool/sync_default_gems.rb: Added sync task for bundler. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@65509 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'man/bundle-config.1.txt')
-rw-r--r--man/bundle-config.1.txt513
1 files changed, 513 insertions, 0 deletions
diff --git a/man/bundle-config.1.txt b/man/bundle-config.1.txt
new file mode 100644
index 0000000000..0a999e8a97
--- /dev/null
+++ b/man/bundle-config.1.txt
@@ -0,0 +1,513 @@
+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 loads configuration settings in this order:
+
+ 1. Local config (1mapp/.bundle/config22m)
+
+ 2. Environmental variables (1mENV22m)
+
+ 3. Global config (1m~/.bundle/config22m)
+
+ 4. Bundler default config
+
+
+
+ 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) 4mbun-0m
+ 4mdle-install.1.html24m prevents Bundler from installing certain groups
+ specified in the Gemfile(5). Bundler persists this value in 1mapp/.bun-0m
+ 1mdle/config 22mso that calls to 1mBundler.setup 22mdo not try to find gems from
+ the 1mGemfile 22mthat you didn't install. Additionally, subsequent calls to
+ bundle install(1) 4mbundle-install.1.html24m 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) 4mbun-0m
+ 4mdle-install.1.html24m.
+
+ 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_platform_warnings 22m(1mBUNDLE_DISABLE_PLATFORM_WARNINGS22m): Dis-
+ able warnings during bundle install when a dependency is unused on
+ the current platform.
+
+ 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 1mglobal_path_appends_ruby_scope 22m(1mBUN-0m
+ 1mDLE_GLOBAL_PATH_APPENDS_RUBY_SCOPE22m): Whether Bundler should append
+ the Ruby scope (e.g. engine and ABI version) to a globally-config-
+ ured path.
+
+ 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 1mpath_relative_to_cwd 22m(1mPATH_RELATIVE_TO_CWD22m) Makes 1m--path 22mrelative
+ to the CWD instead of the 1mGemfile22m.
+
+ 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) 4mbundle-install.1.html24m or bun-
+ dle package(1) 4mbundle-package.1.html24m 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
+
+
+
+
+
+
+ October 2018 BUNDLE-CONFIG(1)