diff options
Diffstat (limited to 'man/bundle-config.1.txt')
-rw-r--r-- | man/bundle-config.1.txt | 513 |
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) |