diff options
Diffstat (limited to 'man/bundle-exec.1.txt')
| -rw-r--r-- | man/bundle-exec.1.txt | 165 |
1 files changed, 84 insertions, 81 deletions
diff --git a/man/bundle-exec.1.txt b/man/bundle-exec.1.txt index ebdc2fda71..ff2ff62dc9 100644 --- a/man/bundle-exec.1.txt +++ b/man/bundle-exec.1.txt @@ -1,4 +1,4 @@ -BUNDLE-EXEC(1) BUNDLE-EXEC(1) +BUNDLE-EXEC(1) BUNDLE-EXEC(1) @@ -9,47 +9,48 @@ SYNOPSIS bundle exec [--keep-file-descriptors] command DESCRIPTION - This command executes the command, making all gems specified in the + This command executes the command, making all gems specified in the [Gemfile(5)][Gemfile(5)] available to require in Ruby programs. - Essentially, if you would normally have run something like rspec - spec/my_spec.rb, and you want to use the gems specified in the [Gem- - file(5)][Gemfile(5)] and installed via bundle install(1) bun- - dle-install.1.html, you should run bundle exec rspec spec/my_spec.rb. + Essentially, if you would normally have run something like rspec + spec/my_spec.rb, and you want to use the gems specified in the + [Gemfile(5)][Gemfile(5)] and installed via bundle install(1) + bundle-install.1.html, you should run bundle exec rspec + spec/my_spec.rb. - Note that bundle exec does not require that an executable is available + Note that bundle exec does not require that an executable is available on your shell's $PATH. OPTIONS --keep-file-descriptors - Exec in Ruby 2.0 began discarding non-standard file descriptors. - When this flag is passed, exec will revert to the 1.9 behaviour - of passing all file descriptors to the new process. + Exec in Ruby 2.0 began discarding non-standard file descriptors. + When this flag is passed, exec will revert to the 1.9 behaviour + of passing all file descriptors to the new process. BUNDLE INSTALL --BINSTUBS - If you use the --binstubs flag in bundle install(1) bun- - dle-install.1.html, Bundler will automatically create a directory - (which defaults to app_root/bin) containing all of the executables + If you use the --binstubs flag in bundle install(1) + bundle-install.1.html, Bundler will automatically create a directory + (which defaults to app_root/bin) containing all of the executables available from gems in the bundle. - After using --binstubs, bin/rspec spec/my_spec.rb is identical to bun- - dle exec rspec spec/my_spec.rb. + After using --binstubs, bin/rspec spec/my_spec.rb is identical to + bundle exec rspec spec/my_spec.rb. ENVIRONMENT MODIFICATIONS - bundle exec makes a number of changes to the shell environment, then + bundle exec makes a number of changes to the shell environment, then executes the command you specify in full. - o make sure that it's still possible to shell out to bundle from - inside a command invoked by bundle exec (using $BUNDLE_BIN_PATH) + o make sure that it's still possible to shell out to bundle from + inside a command invoked by bundle exec (using $BUNDLE_BIN_PATH) - o put the directory containing executables (like rails, rspec, - rackup) for your bundle on $PATH + o put the directory containing executables (like rails, rspec, + rackup) for your bundle on $PATH - o make sure that if bundler is invoked in the subshell, it uses the - same Gemfile (by setting BUNDLE_GEMFILE) + o make sure that if bundler is invoked in the subshell, it uses the + same Gemfile (by setting BUNDLE_GEMFILE) - o add -rbundler/setup to $RUBYOPT, which makes sure that Ruby pro- - grams invoked in the subshell can see the gems in the bundle + o add -rbundler/setup to $RUBYOPT, which makes sure that Ruby + programs invoked in the subshell can see the gems in the bundle @@ -57,122 +58,124 @@ ENVIRONMENT MODIFICATIONS o disallow loading additional gems not in the bundle - o modify the gem method to be a no-op if a gem matching the require- - ments is in the bundle, and to raise a Gem::LoadError if it's not + o modify the gem method to be a no-op if a gem matching the + requirements is in the bundle, and to raise a Gem::LoadError if + it's not - o Define Gem.refresh to be a no-op, since the source index is always - frozen when using bundler, and to prevent gems from the system - leaking into the environment + o Define Gem.refresh to be a no-op, since the source index is always + frozen when using bundler, and to prevent gems from the system + leaking into the environment - o Override Gem.bin_path to use the gems in the bundle, making system - executables work + o Override Gem.bin_path to use the gems in the bundle, making system + executables work o Add all gems in the bundle into Gem.loaded_specs - Finally, bundle exec also implicitly modifies Gemfile.lock if the lock- - file and the Gemfile do not match. Bundler needs the Gemfile to deter- - mine things such as a gem's groups, autorequire, and platforms, etc., - and that information isn't stored in the lockfile. The Gemfile and - lockfile must be synced in order to bundle exec successfully, so bundle - exec updates the lockfile beforehand. + Finally, bundle exec also implicitly modifies Gemfile.lock if the + lockfile and the Gemfile do not match. Bundler needs the Gemfile to + determine things such as a gem's groups, autorequire, and platforms, + etc., and that information isn't stored in the lockfile. The Gemfile + and lockfile must be synced in order to bundle exec successfully, so + bundle exec updates the lockfile beforehand. Loading - By default, when attempting to bundle exec to a file with a ruby she- - bang, Bundler will Kernel.load that file instead of using Kernel.exec. - For the vast majority of cases, this is a performance improvement. In a - rare few cases, this could cause some subtle side-effects (such as - dependence on the exact contents of $0 or __FILE__) and the optimiza- - tion can be disabled by enabling the disable_exec_load setting. + By default, when attempting to bundle exec to a file with a ruby + shebang, Bundler will Kernel.load that file instead of using + Kernel.exec. For the vast majority of cases, this is a performance + improvement. In a rare few cases, this could cause some subtle + side-effects (such as dependence on the exact contents of $0 or + __FILE__) and the optimization can be disabled by enabling the + disable_exec_load setting. Shelling out - Any Ruby code that opens a subshell (like system, backticks, or %x{}) - will automatically use the current Bundler environment. If you need to - shell out to a Ruby command that is not part of your current bundle, - use the with_clean_env method with a block. Any subshells created - inside the block will be given the environment present before Bundler - was activated. For example, Homebrew commands run Ruby, but don't work + Any Ruby code that opens a subshell (like system, backticks, or %x{}) + will automatically use the current Bundler environment. If you need to + shell out to a Ruby command that is not part of your current bundle, + use the with_clean_env method with a block. Any subshells created + inside the block will be given the environment present before Bundler + was activated. For example, Homebrew commands run Ruby, but don't work inside a bundle: - Bundler.with_clean_env do - `brew install wget` - end + Bundler.with_clean_env do + `brew install wget` + end - Using with_clean_env is also necessary if you are shelling out to a - different bundle. Any Bundler commands run in a subshell will inherit - the current Gemfile, so commands that need to run in the context of a + Using with_clean_env is also necessary if you are shelling out to a + different bundle. Any Bundler commands run in a subshell will inherit + the current Gemfile, so commands that need to run in the context of a different bundle also need to use with_clean_env. - Bundler.with_clean_env do - Dir.chdir "/other/bundler/project" do - `bundle exec ./script` - end - end + Bundler.with_clean_env do + Dir.chdir "/other/bundler/project" do + `bundle exec ./script` + end + end - Bundler provides convenience helpers that wrap system and exec, and + Bundler provides convenience helpers that wrap system and exec, and they can be used like this: - Bundler.clean_system('brew install wget') - Bundler.clean_exec('brew install wget') + Bundler.clean_system('brew install wget') + Bundler.clean_exec('brew install wget') RUBYGEMS PLUGINS - At present, the Rubygems plugin system requires all files named - rubygems_plugin.rb on the load path of any installed gem when any Ruby + At present, the Rubygems plugin system requires all files named + rubygems_plugin.rb on the load path of any installed gem when any Ruby code requires rubygems.rb. This includes executables installed into the system, like rails, rackup, and rspec. - Since Rubygems plugins can contain arbitrary Ruby code, they commonly + Since Rubygems plugins can contain arbitrary Ruby code, they commonly end up activating themselves or their dependencies. - For instance, the gemcutter 0.5 gem depended on json_pure. If you had - that version of gemcutter installed (even if you also had a newer ver- - sion without this problem), Rubygems would activate gemcutter 0.5 and - json_pure <latest>. + For instance, the gemcutter 0.5 gem depended on json_pure. If you had + that version of gemcutter installed (even if you also had a newer + version without this problem), Rubygems would activate gemcutter 0.5 + and json_pure <latest>. If your Gemfile(5) also contained json_pure (or a gem with a dependency - on json_pure), the latest version on your system might conflict with - the version in your Gemfile(5), or the snapshot version in your Gem- - file.lock. + on json_pure), the latest version on your system might conflict with + the version in your Gemfile(5), or the snapshot version in your + Gemfile.lock. If this happens, bundler will say: - You have already activated json_pure 1.4.6 but your Gemfile - requires json_pure 1.4.3. Consider using bundle exec. + You have already activated json_pure 1.4.6 but your Gemfile + requires json_pure 1.4.3. Consider using bundle exec. - In this situation, you almost certainly want to remove the underlying - gem with the problematic gem plugin. In general, the authors of these - plugins (in this case, the gemcutter gem) have released newer versions + In this situation, you almost certainly want to remove the underlying + gem with the problematic gem plugin. In general, the authors of these + plugins (in this case, the gemcutter gem) have released newer versions that are more careful in their plugins. You can find a list of all the gems containing gem plugins by running - ruby -rrubygems -e "puts Gem.find_files('rubygems_plugin.rb')" + ruby -rrubygems -e "puts Gem.find_files('rubygems_plugin.rb')" At the very least, you should remove all but the newest version of each - gem plugin, and also remove all gem plugins that you aren't using (gem + gem plugin, and also remove all gem plugins that you aren't using (gem uninstall gem_name). - January 2020 BUNDLE-EXEC(1) + May 2020 BUNDLE-EXEC(1) |