Edit config & install docs re: remembered flags

3 files changed, 47 insertions, 42 deletions

diff --git a/lib/bundler/ui/shell.rb b/lib/bundler/ui/shell.rb
index 5509113b4b..8db69c47d0 100644
--- a/lib/bundler/ui/shell.rb
+++ b/lib/bundler/ui/shell.rb
@@ -39,7 +39,7 @@ module Bundler
       def deprecate(msg, newline = nil)
         return if @deprecation_messages.include?(msg)
         @deprecation_messages.add(msg)
-        warn("DEPRECATION: " + msg, newline)
+        tell_err("DEPRECATION: " + msg, :yellow, newline)
       end
 
       def error(msg, newline = nil)
@@ -102,6 +102,14 @@ module Bundler
         end
       end
 
+      def tell_err(message, color = nil, newline = nil)
+        buffer = @shell.send(:prepare_message, message, *color)
+        buffer << "\n" if newline && !message.to_s.end_with?("\n")
+
+        @shell.send(:stderr).print(buffer)
+        @shell.send(:stderr).flush
+      end
+
       def strip_leading_spaces(text)
         spaces = text[/\A\s+/, 0]
         spaces ? text.gsub(/#{spaces}/, "") : text
diff --git a/man/bundle-config.ronn b/man/bundle-config.ronn
index d617ae340b..3ea6d10973 100644
--- a/man/bundle-config.ronn
+++ b/man/bundle-config.ronn
@@ -39,6 +39,38 @@ Executing `bundle config disable_multisource true` upgrades the warning about
 the Gemfile containing multiple primary sources to an error. Executing `bundle
 config --delete disable_multisource` downgrades this error to a warning.
 
+## REMEMBERING OPTIONS
+
+Flags passed to `bundle install` or the Bundler runtime,
+such as `--path foo` or `--without production`, are not remembered between commands.
+If these options must be remembered,they must be set using `bundle config`
+(e.g., `bundle config path foo`).
+
+The options that can be configured are:
+
+* `binstubs`:
+  Creates a directory (defaults to `~/bin`) and place any executables from the
+  gem there. These executables run in Bundler's context. If used, you might add
+  this directory to your environment's `PATH` variable. For instance, if the
+  `rails` gem comes with a `rails` executable, this flag will create a
+  `bin/rails` executable that ensures that all referred dependencies will be
+  resolved using the bundled gems.
+
+* `deployment`:
+  In deployment mode, Bundler will 'roll-out' the bundle for
+  `production` use. Please check carefully if you want to have this option
+  enabled in `development` or `test` environments.
+
+* `path`:
+  The location to install the specified gems to. This defaults to Rubygems'
+  setting. Bundler shares this location with Rubygems, `gem install ...` will
+  have gem installed there, too. Therefore, gems installed without a
+  `--path ...` setting will show up by calling `gem list`. Accodingly, gems
+  installed to other locations will not get listed.
+
+* `without`:
+  A space-separated list of groups referencing gems to skip during installation.
+
 ## BUILD OPTIONS
 
 You can use `bundle config` to give bundler the flags to pass to the gem
diff --git a/man/bundle-install.ronn b/man/bundle-install.ronn
index b5391fa024..92d1d8d42c 100644
--- a/man/bundle-install.ronn
+++ b/man/bundle-install.ronn
@@ -43,6 +43,9 @@ update process below under [CONSERVATIVE UPDATING][].
 
 ## OPTIONS
 
+To apply any of `--deployment`, `--path`, `--binstubs`, or `--without` every
+time `bundle install` is run, use `bundle config` (see bundle-config(1)).
+
 * `--binstubs[=<directory>]`:
   Creates a directory (defaults to `~/bin`) and place any executables from the
   gem there. These executables run in Bundler's context. If used, you might add
@@ -93,7 +96,7 @@ update process below under [CONSERVATIVE UPDATING][].
 
 * `--system`:
   Installs the gems specified in the bundle to the system's Rubygems location.
-  This overrides any previous [remembered][REMEMBERED OPTIONS] use of `--path`.
+  This overrides any previous configuration of `--path`.
 
 * `--no-cache`:
   Do not update the cache in `vendor/cache` with the newly bundled gems. This
@@ -108,8 +111,7 @@ update process below under [CONSERVATIVE UPDATING][].
   setting. Bundler shares this location with Rubygems, `gem install ...` will
   have gem installed there, too. Therefore, gems installed without a
   `--path ...` setting will show up by calling `gem list`. Accodingly, gems
-  installed to other locations will not get listed. This setting is a
-  [remembered option][REMEMBERED OPTIONS].
+  installed to other locations will not get listed.
 
 * `--quiet`:
   Do not print progress information to the standard output. Instead, Bundler
@@ -142,14 +144,12 @@ update process below under [CONSERVATIVE UPDATING][].
   A space-separated list of groups referencing gems to skip during installation.
   If a group is given that is in the remembered list of groups given
   to --with, it is removed from that list.
-  This is a [remembered option][REMEMBERED OPTIONS].
 
 * `--with=<list>`:
   A space-separated list of groups referencing gems to install. If an
   optional group is given it is installed. If a group is given that is
   in the remembered list of groups given to --without, it is removed
-  from that list. This is a [remembered option][REMEMBERED OPTIONS].
-
+  from that list.
 
 ## DEPLOYMENT MODE
 
@@ -274,41 +274,6 @@ the vagaries of the dependency resolution process, this usually
 affects more than the gems you list in your Gemfile(5), and can
 (surprisingly) radically change the gems you are using.
 
-## REMEMBERED OPTIONS
-
-Some options (marked above in the [OPTIONS][] section) are remembered
-between calls to `bundle install`, and by the Bundler runtime.
-
-For instance, if you run `bundle install --without test`, a subsequent
-call to `bundle install` that does not include a `--without` flag will
-remember your previous choice.
-
-In addition, a call to `Bundler.setup` will not attempt to make the
-gems in those groups available on the Ruby load path, as they were
-not installed.
-
-The settings that are remembered are:
-
-* `--deployment`:
-  At runtime, this remembered setting will also result in Bundler
-  raising an exception if the `Gemfile.lock` is out of date.
-
-* `--path`:
-  Subsequent calls to `bundle install` will install gems to the
-  directory originally passed to `--path`. The Bundler runtime
-  will look for gems in that location. You can revert this
-  option by running `bundle install --system`.
-
-* `--binstubs`:
-  Bundler will update the executables every subsequent call to
-  `bundle install`.
-
-* `--without`:
-  As described above, Bundler will skip the gems specified by
-  `--without` in subsequent calls to `bundle install`. The
-  Bundler runtime will also not try to make the gems in the
-  skipped groups available.
-
 ## THE GEMFILE.LOCK
 
 When you run `bundle install`, Bundler will persist the full names