Add bundle config and bundle exec

2 files changed, 188 insertions, 0 deletions

diff --git a/man/bundle-config.ronn b/man/bundle-config.ronn
new file mode 100644
index 00000000..50408723
--- /dev/null
+++ b/man/bundle-config.ronn
@@ -0,0 +1,90 @@
+bundle-config(1) -- Set bundler configuration options
+=====================================================
+
+## SYNOPSIS
+
+`bundle config` [<name> [<value>]]
+
+## DESCRIPTION
+
+This command allows you to interact with bundler's configuration system.
+Bundler retrieves its configuration from the local application (`app/.bundle/config),
+environment variables, and the user's home directory (`~/.bundle/config),
+in that order of priority.
+
+Executing `bundle config` with no parameters will print a list of all
+bundler configuration for the current bundle, and where that configuration
+was set.
+
+Executing `bundle config <name>` will print the value of that configuration
+setting, and where it was set.
+
+Executing `bundle config <name> <value>` will set that configuration to the
+value specified for all bundles executed as the current user. The configuration
+will be stored in `~/.bundle/config`.
+
+## BUILD OPTIONS
+
+You can use `bundle config` to give bundler the flags to pass to the gem
+installer every time bundler tries to install a particular gem.
+
+A very common example, the `mysql` gem, requires Snow Leopard users to
+pass configuration flags to `gem install` to specify where to find the
+`mysql_config` executable.
+
+    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
+`mysql` gem, it will pass along the flags you specified.
+
+## CONFIGURATION KEYS
+
+Configuration keys in bundler have two forms: the canonical form and the
+environment variable form.
+
+For instance, passing the `--without` flag to `bundle install(1)` prevents
+Bundler from installing certain groups specified in the `Gemfile(1)`. Bundler
+persists this value in `app/.bundle/config` so that calls to `Bundler.setup`
+do not try to find gems from the `Gemfile` that you didn't install. Additionally,
+subsequent calls to `bundle install(1)` remember this setting and skip those
+groups.
+
+The canonical form of this configuration is `"without"`. To convert the canonical
+form to the environment variable form, capitalize it, and prepend `BUNDLE_`. The
+environment variable form of `"without"` is `BUNDLE_WITHOUT`.
+
+## LIST OF AVAILABLE KEYS
+
+The following is a list of all configuration keys and their purpose. You can
+learn more about their operation in `bundle install(1)`.
+
+* `path` (`BUNDLE_PATH`):
+  The location on disk to install gems. Defaults to `$GEM_HOME` in development
+  and `vendor/bundler` when `--deployment` is used
+* `frozen` (`BUNDLE_FROZEN`):
+  Disallow changes to the `Gemfile`. Defaults to `true` when `--deployment`
+  is used.
+* `without` (`BUNDLE_WITHOUT`):
+  A `:`-separated list of groups whose gems bundler should not install
+* `bin` (`BUNDLE_BIN`):
+  Install executables from gems in the bundle to the specified directory.
+  Defaults to `false`.
+* `gemfile` (`BUNDLE_GEMFILE`):
+  The name of the file that bundler should use as the `Gemfile`. This location
+  of this file also sets the root of the project, which is used to resolve
+  relative paths in the `Gemfile`, among other things. By default, bundler
+  will search up from the current working directory until it finds a
+  `Gemfile`.
+
+In general, you should set these settings per-application by using the applicable
+flag to the `bundle install(1)` command.
+
+You can set them globally either via environment variables or `bundle config`,
+whichever is preferable for your setup. If you use both, environment variables
+will take preference over global settings.
+
diff --git a/man/bundle-exec.ronn b/man/bundle-exec.ronn
new file mode 100644
index 00000000..b2fe9a25
--- /dev/null
+++ b/man/bundle-exec.ronn
@@ -0,0 +1,98 @@
+bundle-exec(1) -- Execute a command in the context of the bundle
+================================================================
+
+## SYNOPSIS
+
+`bundle exec` <command>
+
+## DESCRIPTION
+
+This command executes the command, making all gems specified in the
+`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 `Gemfile(5)` and installed via `bundle install(1)`, 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`.
+
+## BUNDLE INSTALL --BINSTUBS
+
+If you use the `--binstubs` flag in `bundle install(1)`, 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 `bundle 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.
+
+* make sure that it's still possible to shell out to `bundle`
+  from inside a command invoked by `bundle exec` (using
+  `$BUNDLE_BIN_PATH`)
+* put the directory containing executables (like `rails`, `rspec`,
+  `rackup`) for your bundle on `$PATH`
+* make sure that if bundler is invoked in the subshell, it uses
+  the same `Gemfile` (by setting `BUNDLE_GEMFILE`)
+* add `-rbundler/setup` to `$RUBYOPT`, which makes sure that
+  Ruby programs invoked in the subshell can see the gems in
+  the bundle
+
+It also modifies Rubygems:
+
+* disallow loading additional gems not in the bundle
+* 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
+* 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
+* Override `Gem.bin_path` to use the gems in the bundle,
+  making system executables work
+* Add all gems in the bundle into Gem.loaded_specs
+
+## 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 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 `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.
+
+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`).