1BUNDLE-EXEC(1) BUNDLE-EXEC(1)
2
6 bundle-exec - Execute a command in the context of the bundle
7
9 bundle exec [--keep-file-descriptors] command
10
12 This command executes the command, making all gems specified in the
13 Gemfile(5) available to require in Ruby programs.
14 Essentially, if you would normally have run something like rspec
16 spec/my_spec.rb, and you want to use the gems specified in the Gem‐
17 file(5) and installed via bundle install(1) bundle-install.1.html, you
18 should run bundle exec rspec spec/my_spec.rb.
19 Note that bundle exec does not require that an executable is available
21 on your shell´s $PATH.
22
24 --keep-file-descriptors
25 Exec in Ruby 2.0 began discarding non-standard file descriptors.
26 When this flag is passed, exec will revert to the 1.9 behaviour
27 of passing all file descriptors to the new process.
28
30 If you use the --binstubs flag in bundle install(1) bun‐
31 dle-install.1.html, Bundler will automatically create a directory
32 (which defaults to app_root/bin) containing all of the executables
33 available from gems in the bundle.
34 After using --binstubs, bin/rspec spec/my_spec.rb is identical to bun‐
36 dle exec rspec spec/my_spec.rb.
37
39 bundle exec makes a number of changes to the shell environment, then
40 executes the command you specify in full.
41 · make sure that it´s still possible to shell out to bundle from
43 inside a command invoked by bundle exec (using $BUNDLE_BIN_PATH)
44 · put the directory containing executables (like rails, rspec,
46 rackup) for your bundle on $PATH
47 · make sure that if bundler is invoked in the subshell, it uses the
49 same Gemfile (by setting BUNDLE_GEMFILE)
50 · add -rbundler/setup to $RUBYOPT, which makes sure that Ruby pro‐
52 grams invoked in the subshell can see the gems in the bundle
53 It also modifies Rubygems:
57 · disallow loading additional gems not in the bundle
59 · modify the gem method to be a no-op if a gem matching the require‐
61 ments is in the bundle, and to raise a Gem::LoadError if it´s not
62 · Define Gem.refresh to be a no-op, since the source index is always
64 frozen when using bundler, and to prevent gems from the system
65 leaking into the environment
66 · Override Gem.bin_path to use the gems in the bundle, making system
68 executables work
69 · Add all gems in the bundle into Gem.loaded_specs
71 Shelling out
75 Any Ruby code that opens a subshell (like system, backticks, or %x{})
76 will automatically use the current Bundler environment. If you need to
77 shell out to a Ruby command that is not part of your current bundle,
78 use the with_clean_env method with a block. Any subshells created
79 inside the block will be given the environment present before Bundler
80 was activated. For example, Homebrew commands run Ruby, but don´t work
81 inside a bundle:
82 Bundler.with_clean_env do
86 `brew install wget`
87 end
88 Using with_clean_env is also necessary if you are shelling out to a
92 different bundle. Any Bundler commands run in a subshell will inherit
93 the current Gemfile, so commands that need to run in the context of a
94 different bundle also need to use with_clean_env.
95 Bundler.with_clean_env do
99 Dir.chdir "/other/bundler/project" do
100 `bundle exec ./script`
101 end
102 end
103 Bundler provides convenience helpers that wrap system and exec, and
107 they can be used like this:
108 Bundler.clean_system(´brew install wget´)
112 Bundler.clean_exec(´brew install wget´)
113
117 At present, the Rubygems plugin system requires all files named
118 rubygems_plugin.rb on the load path of any installed gem when any Ruby
119 code requires rubygems.rb. This includes executables installed into the
120 system, like rails, rackup, and rspec.
121 Since Rubygems plugins can contain arbitrary Ruby code, they commonly
123 end up activating themselves or their dependencies.
124 For instance, the gemcutter 0.5 gem depended on json_pure. If you had
126 that version of gemcutter installed (even if you also had a newer ver‐
127 sion without this problem), Rubygems would activate gemcutter 0.5 and
128 json_pure <latest>.
129 If your Gemfile(5) also contained json_pure (or a gem with a dependency
131 on json_pure), the latest version on your system might conflict with
132 the version in your Gemfile(5), or the snapshot version in your Gem‐
133 file.lock.
134 If this happens, bundler will say:
136 You have already activated json_pure 1.4.6 but your Gemfile
140 requires json_pure 1.4.3. Consider using bundle exec.
141 In this situation, you almost certainly want to remove the underlying
145 gem with the problematic gem plugin. In general, the authors of these
146 plugins (in this case, the gemcutter gem) have released newer versions
147 that are more careful in their plugins.
148 You can find a list of all the gems containing gem plugins by running
150 ruby -rubygems -e "puts Gem.find_files(´rubygems_plugin.rb´)"
154 At the very least, you should remove all but the newest version of each
158 gem plugin, and also remove all gem plugins that you aren´t using (gem
159 uninstall gem_name).
160 July 2014 BUNDLE-EXEC(1)