diff options
Diffstat (limited to 'man/bundle-exec.1.txt')
| -rw-r--r-- | man/bundle-exec.1.txt | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/man/bundle-exec.1.txt b/man/bundle-exec.1.txt new file mode 100644 index 0000000000..f01a0ce04a --- /dev/null +++ b/man/bundle-exec.1.txt @@ -0,0 +1,178 @@ +BUNDLE-EXEC(1) BUNDLE-EXEC(1) + + + +NAME + bundle-exec - Execute a command in the context of the bundle + +SYNOPSIS + bundle exec [--keep-file-descriptors] command + +DESCRIPTION + 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. + + 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. + +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 + 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. + +ENVIRONMENT MODIFICATIONS + 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 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 add -rbundler/setup to $RUBYOPT, which makes sure that Ruby pro- + grams invoked in the subshell can see the gems in the bundle + + + + It also modifies Rubygems: + + 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 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 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. + + 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. + + 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 + inside a bundle: + + + + 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 + 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 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') + + + +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 + 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 + 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>. + + 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. + + 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. + + + + 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 -rubygems -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 + uninstall gem_name). + + + + August 2019 BUNDLE-EXEC(1) |