* lib/rubygems: Import RubyGems 2.1.0 Release Candidate

* test/rubygems:  ditto.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@42693 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

24 files changed, 294 insertions, 32 deletions

diff --git a/lib/rubygems/commands/build_command.rb b/lib/rubygems/commands/build_command.rb
index 64563ed3db..d975429fe8 100644
--- a/lib/rubygems/commands/build_command.rb
+++ b/lib/rubygems/commands/build_command.rb
@@ -15,6 +15,25 @@ class Gem::Commands::BuildCommand < Gem::Command
     "GEMSPEC_FILE  gemspec file name to build a gem for"
   end
 
+  def description # :nodoc:
+    <<-EOF
+The build command allows you to create a gem from a ruby gemspec.
+
+The best way to build a gem is to use a Rakefile and the Gem::PackageTask
+which ships with RubyGems.
+
+The gemspec can either be created by hand or extracted from an existing gem
+with gem spec:
+
+  $ gem unpack my_gem-1.0.gem
+  Unpacked gem: '.../my_gem-1.0'
+  $ gem spec my_gem-1.0.gem --ruby > my_gem-1.0/my_gem-1.0.gemspec
+  $ cd my_gem-1.0
+  [edit gem contents]
+  $ gem build my_gem-1.0.gemspec
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name} GEMSPEC_FILE"
   end
diff --git a/lib/rubygems/commands/check_command.rb b/lib/rubygems/commands/check_command.rb
index d7677d47a1..8893b9c3b2 100644
--- a/lib/rubygems/commands/check_command.rb
+++ b/lib/rubygems/commands/check_command.rb
@@ -79,6 +79,13 @@ class Gem::Commands::CheckCommand < Gem::Command
     '--gems --alien'
   end
 
+  def description # :nodoc:
+    <<-EOF
+The check command can list and repair problems with installed gems and
+specifications and will clean up gems that have been partially uninstalled.
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name} [OPTIONS] [GEMNAME ...]"
   end
diff --git a/lib/rubygems/commands/cleanup_command.rb b/lib/rubygems/commands/cleanup_command.rb
index cacfe89404..c8f0082bfb 100644
--- a/lib/rubygems/commands/cleanup_command.rb
+++ b/lib/rubygems/commands/cleanup_command.rb
@@ -6,7 +6,7 @@ class Gem::Commands::CleanupCommand < Gem::Command
 
   def initialize
     super 'cleanup',
-          'Clean up old versions of installed gems in the local repository',
+          'Clean up old versions of installed gems',
           :force => false, :install_dir => Gem.dir
 
     add_option('-n', '-d', '--dryrun',
@@ -33,11 +33,11 @@ class Gem::Commands::CleanupCommand < Gem::Command
 
   def description # :nodoc:
     <<-EOF
-The cleanup command removes old gems from GEM_HOME.  If an older version is
-installed elsewhere in GEM_PATH the cleanup command won't touch it.
+The cleanup command removes old versions of gems from GEM_HOME that are not
+required to meet a dependency.  If a gem is installed elsewhere in GEM_PATH
+the cleanup command won't delete it.
 
-Older gems that are required to satisify the dependencies of gems
-are not removed.
+If no gems are named all gems in GEM_HOME are cleaned.
     EOF
   end
 
diff --git a/lib/rubygems/commands/contents_command.rb b/lib/rubygems/commands/contents_command.rb
index 9ba24895dc..97218848ed 100644
--- a/lib/rubygems/commands/contents_command.rb
+++ b/lib/rubygems/commands/contents_command.rb
@@ -45,6 +45,14 @@ class Gem::Commands::ContentsCommand < Gem::Command
     "--no-lib-only --prefix"
   end
 
+  def description # :nodoc:
+    <<-EOF
+The contents command lists the files in an installed gem.  The listing can
+be given as full file names, file names without the installed directory
+prefix or only the files that are requireable.
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name} GEMNAME [GEMNAME ...]"
   end
diff --git a/lib/rubygems/commands/dependency_command.rb b/lib/rubygems/commands/dependency_command.rb
index f444841ccb..c5d6dd7d70 100644
--- a/lib/rubygems/commands/dependency_command.rb
+++ b/lib/rubygems/commands/dependency_command.rb
@@ -38,6 +38,17 @@ class Gem::Commands::DependencyCommand < Gem::Command
     "--local --version '#{Gem::Requirement.default}' --no-reverse-dependencies"
   end
 
+  def description # :nodoc:
+    <<-EOF
+The dependency commands lists which other gems a given gem depends on.  For
+local gems only the reverse dependencies can be shown (which gems depend on
+the named gem).
+
+The dependency list can be displayed in a format suitable for piping for
+use with other commands.
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name} GEMNAME"
   end
diff --git a/lib/rubygems/commands/environment_command.rb b/lib/rubygems/commands/environment_command.rb
index 034f2ccb49..d32d12b757 100644
--- a/lib/rubygems/commands/environment_command.rb
+++ b/lib/rubygems/commands/environment_command.rb
@@ -21,6 +21,9 @@ class Gem::Commands::EnvironmentCommand < Gem::Command
 
   def description # :nodoc:
     <<-EOF
+The environment command lets you query rubygems for its configuration for
+use in shell scripts or as a debugging aid.
+
 The RubyGems environment can be controlled through command line arguments,
 gemrc files, environment variables and built-in defaults.
 
diff --git a/lib/rubygems/commands/fetch_command.rb b/lib/rubygems/commands/fetch_command.rb
index ec021359b6..b35987c329 100644
--- a/lib/rubygems/commands/fetch_command.rb
+++ b/lib/rubygems/commands/fetch_command.rb
@@ -28,6 +28,16 @@ class Gem::Commands::FetchCommand < Gem::Command
     "--version '#{Gem::Requirement.default}'"
   end
 
+  def description # :nodoc:
+    <<-EOF
+The fetch command fetches gem files that can be stored for later use or
+unpacked to examine their contents.
+
+See the build command help for an example of unpacking a gem, modifying it,
+then repackaging it.
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name} GEMNAME [GEMNAME ...]"
   end
diff --git a/lib/rubygems/commands/list_command.rb b/lib/rubygems/commands/list_command.rb
index f3e5da9551..0d15950475 100644
--- a/lib/rubygems/commands/list_command.rb
+++ b/lib/rubygems/commands/list_command.rb
@@ -8,7 +8,7 @@ require 'rubygems/commands/query_command'
 class Gem::Commands::ListCommand < Gem::Commands::QueryCommand
 
   def initialize
-    super 'list', 'Display gems whose name starts with STRING'
+    super 'list', 'Display local gems whose name starts with STRING'
 
     remove_option('--name-matches')
   end
@@ -21,6 +21,17 @@ class Gem::Commands::ListCommand < Gem::Commands::QueryCommand
     "--local --no-details"
   end
 
+  def description # :nodoc:
+    <<-EOF
+The list command is used to view the gems you have installed locally.
+
+The --details option displays additional details including the summary, the
+homepage, the author, the locations of different versions of the gem.
+
+To search for remote gems use the search command.
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name} [STRING]"
   end
diff --git a/lib/rubygems/commands/mirror_command.rb b/lib/rubygems/commands/mirror_command.rb
index 0f98077cbd..75419c857a 100644
--- a/lib/rubygems/commands/mirror_command.rb
+++ b/lib/rubygems/commands/mirror_command.rb
@@ -10,6 +10,12 @@ class Gem::Commands::MirrorCommand < Gem::Command
     end
   end
 
+  def description # :nodoc:
+    <<-EOF
+The mirror command has been moved to the rubygems-mirror gem.
+    EOF
+  end
+
   def execute
     alert_error "Install the rubygems-mirror gem for the mirror command"
   end
diff --git a/lib/rubygems/commands/outdated_command.rb b/lib/rubygems/commands/outdated_command.rb
index 196d0d67e6..f51bc5e93f 100644
--- a/lib/rubygems/commands/outdated_command.rb
+++ b/lib/rubygems/commands/outdated_command.rb
@@ -15,6 +15,15 @@ class Gem::Commands::OutdatedCommand < Gem::Command
     add_platform_option
   end
 
+  def description # :nodoc:
+    <<-EOF
+The outdated command lists gems you way wish to upgrade to a newer version.
+
+You can check for dependency mismatches using the dependency command and
+update the gems with the update or install commands.
+    EOF
+  end
+
   def execute
     Gem::Specification.outdated_and_latest_version.each do |spec, remote_version|
       say "#{spec.name} (#{spec.version} < #{remote_version})"
diff --git a/lib/rubygems/commands/owner_command.rb b/lib/rubygems/commands/owner_command.rb
index c1c0a570d6..13b8793021 100644
--- a/lib/rubygems/commands/owner_command.rb
+++ b/lib/rubygems/commands/owner_command.rb
@@ -7,7 +7,14 @@ class Gem::Commands::OwnerCommand < Gem::Command
   include Gem::GemcutterUtilities
 
   def description # :nodoc:
-    'Manage gem owners on RubyGems.org.'
+    <<-EOF
+The owner command lets you add and remove owners of a gem on a push
+server (the default is https://rubygems.org).
+
+The owner of a gem has the permission to push new versions, yank existing
+versions or edit the HTML page of the gem.  Be careful of who you give push
+permission to.
+    EOF
   end
 
   def arguments # :nodoc:
@@ -19,7 +26,7 @@ class Gem::Commands::OwnerCommand < Gem::Command
   end
 
   def initialize
-    super 'owner', description
+    super 'owner', 'Manage gem owners of a gem on the push server'
     add_proxy_option
     add_key_option
     defaults.merge! :add => [], :remove => []
diff --git a/lib/rubygems/commands/pristine_command.rb b/lib/rubygems/commands/pristine_command.rb
index 257e6df1cc..3f3bca45be 100644
--- a/lib/rubygems/commands/pristine_command.rb
+++ b/lib/rubygems/commands/pristine_command.rb
@@ -21,7 +21,8 @@ class Gem::Commands::PristineCommand < Gem::Command
     end
 
     add_option('--[no-]extensions',
-               'Restore gems with extensions') do |value, options|
+               'Restore gems with extensions',
+               'in addition to regular gems') do |value, options|
       options[:extensions] = value
     end
 
@@ -49,23 +50,23 @@ class Gem::Commands::PristineCommand < Gem::Command
 
   def description # :nodoc:
     <<-EOF
-The pristine command compares the installed gems with the contents of the
-cached gem and restores any files that don't match the cached gem's copy.
+The pristine command compares an installed gem with the contents of its
+cached .gem file and restores any files that don't match the cached .gem's
+copy.
 
-If you have made modifications to your installed gems, the pristine command
-will revert them.  After all the gem's files have been checked all bin stubs
-for the gem are regenerated.
+If you have made modifications to an installed gem, the pristine command
+will revert them.  All extensions are rebuilt and all bin stubs for the gem
+are regenerated after checking for modifications.
 
-If the cached gem cannot be found, you will need to use `gem install` to
-revert the gem.
+If the cached gem cannot be found it will be downloaded.
 
-If --no-extensions is provided pristine will not attempt to restore gems
-with extensions.
+If --no-extensions is provided pristine will not attempt to restore a gem
+with an extension.
     EOF
   end
 
   def usage # :nodoc:
-    "#{program_name} [args]"
+    "#{program_name} [GEMNAME ...]"
   end
 
   def execute
diff --git a/lib/rubygems/commands/push_command.rb b/lib/rubygems/commands/push_command.rb
index fccad206fa..b90be7bd10 100644
--- a/lib/rubygems/commands/push_command.rb
+++ b/lib/rubygems/commands/push_command.rb
@@ -8,7 +8,13 @@ class Gem::Commands::PushCommand < Gem::Command
   include Gem::GemcutterUtilities
 
   def description # :nodoc:
-    'Push a gem up to RubyGems.org'
+    <<-EOF
+The push command uploads a gem to the push server (the default is
+https://rubygems.org) and adds it to the index.
+
+The gem can be removed from the index (but only the index) using the yank
+command.  For further discussion see the help for the yank command.
+    EOF
   end
 
   def arguments # :nodoc:
@@ -20,7 +26,7 @@ class Gem::Commands::PushCommand < Gem::Command
   end
 
   def initialize
-    super 'push', description, :host => self.host
+    super 'push', 'Push a gem up to the gem server', :host => self.host
 
     add_proxy_option
     add_key_option
diff --git a/lib/rubygems/commands/query_command.rb b/lib/rubygems/commands/query_command.rb
index 05b214bb63..c9c3014975 100644
--- a/lib/rubygems/commands/query_command.rb
+++ b/lib/rubygems/commands/query_command.rb
@@ -61,6 +61,15 @@ class Gem::Commands::QueryCommand < Gem::Command
     "--local --name-matches // --no-details --versions --no-installed"
   end
 
+  def description # :nodoc:
+    <<-EOF
+The query command is the basis for the list and search commands.
+
+You should really use the list and search commands instead.  This command
+is too hard to use.
+    EOF
+  end
+
   def execute
     exit_code = 0
 
diff --git a/lib/rubygems/commands/rdoc_command.rb b/lib/rubygems/commands/rdoc_command.rb
index df00f3a5df..86597f99a6 100644
--- a/lib/rubygems/commands/rdoc_command.rb
+++ b/lib/rubygems/commands/rdoc_command.rb
@@ -45,8 +45,12 @@ class Gem::Commands::RdocCommand < Gem::Command
 
   def description # :nodoc:
     <<-DESC
-The rdoc command builds RDoc and RI documentation for installed gems.  Use
---overwrite to force rebuilding of documentation.
+The rdoc command builds documentation for installed gems.  By default
+only documentation is built using rdoc, but additional types of
+documentation may be built through rubygems plugins and the
+Gem.post_installs hook.
+
+Use --overwrite to force rebuilding of documentation.
     DESC
   end
 
diff --git a/lib/rubygems/commands/search_command.rb b/lib/rubygems/commands/search_command.rb
index c125715fe2..5bc9650672 100644
--- a/lib/rubygems/commands/search_command.rb
+++ b/lib/rubygems/commands/search_command.rb
@@ -4,7 +4,7 @@ require 'rubygems/commands/query_command'
 class Gem::Commands::SearchCommand < Gem::Commands::QueryCommand
 
   def initialize
-    super 'search', 'Display all gems whose name contains STRING'
+    super 'search', 'Display remote gems whose name contains STRING'
 
     remove_option '--name-matches'
 
@@ -19,6 +19,19 @@ class Gem::Commands::SearchCommand < Gem::Commands::QueryCommand
     "--remote --no-details"
   end
 
+  def description # :nodoc:
+    <<-EOF
+The search command displays remote gems whose name contains the given
+string.
+
+The --details option displays additional details from the gem but will
+take a little longer to complete as it must download the information
+individually from the index.
+
+To list local gems use the list command.
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name} [STRING]"
   end
diff --git a/lib/rubygems/commands/sources_command.rb b/lib/rubygems/commands/sources_command.rb
index 810b45d7c0..60d96c5828 100644
--- a/lib/rubygems/commands/sources_command.rb
+++ b/lib/rubygems/commands/sources_command.rb
@@ -97,6 +97,53 @@ Do you want to add this insecure source?
     '--list'
   end
 
+  def description # :nodoc:
+    <<-EOF
+RubyGems fetches gems from the sources you have configured (stored in your
+~/.gemrc).
+
+The default source is https://rubygems.org, but you may have older sources
+configured.  This guide will help you update your sources or configure
+yourself to use your own gem server.
+
+Without any arguments the sources lists your currently configured sources:
+
+  $ gem sources
+  *** CURRENT SOURCES ***
+
+  https://rubygems.org
+
+This may list multiple sources or non-rubygems sources.  You probably
+configured them before or have an old `~/.gemrc`.  If you have sources you
+do not recognize you should remove them.
+
+RubyGems has been configured to serve gems via the following URLs through
+its history:
+
+* http://gems.rubyforge.org (RubyGems 1.3.6 and earlier)
+* http://rubygems.org       (RubyGems 1.3.7 through 1.8.25)
+* https://rubygems.org      (RubyGems 2.0.1 and newer)
+
+Since all of these sources point to the same set of gems you only need one
+of them in your list.  https://rubygems.org is recommended as it brings the
+protections of an SSL connection to gem downloads.
+
+To add a source use the --add argument:
+
+    $ gem sources --add https://rubygems.org
+    https://rubygems.org added to sources
+
+RubyGems will check to see if gems can be installed from the source given
+before it is added.
+
+To remove a source use the --remove argument:
+
+    $ gem sources --remove http://rubygems.org
+    http://rubygems.org removed from sources
+
+    EOF
+  end
+
   def list # :nodoc:
     say "*** CURRENT SOURCES ***"
     say
diff --git a/lib/rubygems/commands/specification_command.rb b/lib/rubygems/commands/specification_command.rb
index b40dfd5f3c..d96c8b8627 100644
--- a/lib/rubygems/commands/specification_command.rb
+++ b/lib/rubygems/commands/specification_command.rb
@@ -50,6 +50,22 @@ FIELD         name of gemspec field to show
     "--local --version '#{Gem::Requirement.default}' --yaml"
   end
 
+  def description # :nodoc:
+    <<-EOF
+The specification command allows you to extract the specification from
+a gem for examination.
+
+The specification can be output in YAML, ruby or Marshal formats.
+
+Specific fields in the specification can be extracted in YAML format:
+
+  $ gem spec rake summary
+  --- Ruby based make-like utility.
+  ...
+
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name} [GEMFILE] [FIELD]"
   end
diff --git a/lib/rubygems/commands/stale_command.rb b/lib/rubygems/commands/stale_command.rb
index 36c517e27c..0ef0755960 100644
--- a/lib/rubygems/commands/stale_command.rb
+++ b/lib/rubygems/commands/stale_command.rb
@@ -5,6 +5,16 @@ class Gem::Commands::StaleCommand < Gem::Command
     super('stale', 'List gems along with access times')
   end
 
+  def description # :nodoc:
+    <<-EOF
+The stale command lists the latest access time for all the files in your
+installed gems.
+
+You can use this command to discover gems and gem versions you are no
+longer using.
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name}"
   end
diff --git a/lib/rubygems/commands/uninstall_command.rb b/lib/rubygems/commands/uninstall_command.rb
index 5db8a1ff22..8e6af2ba65 100644
--- a/lib/rubygems/commands/uninstall_command.rb
+++ b/lib/rubygems/commands/uninstall_command.rb
@@ -88,6 +88,16 @@ class Gem::Commands::UninstallCommand < Gem::Command
     "--user-install"
   end
 
+  def description # :nodoc:
+    <<-EOF
+The uninstall command removes a previously installed gem.
+
+RubyGems will ask for confirmation if you are attempting to uninstall a gem
+that is a dependency of an existing gem.  You can use the
+--ignore-dependencies option to skip this check.
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name} GEMNAME [GEMNAME ...]"
   end
@@ -104,15 +114,18 @@ class Gem::Commands::UninstallCommand < Gem::Command
   end
 
   def uninstall_all
-    install_dir = options[:install_dir]
+    _, specs = Gem::Specification.partition { |spec| spec.default_gem? }
 
-    dirs_to_be_emptied = Dir[File.join(install_dir, '*')]
-    dirs_to_be_emptied.delete_if { |dir| dir.end_with? 'build_info' }
+    specs.each do |spec|
+      options[:version] = spec.version
 
-    dirs_to_be_emptied.each do |dir|
-      FileUtils.rm_rf Dir[File.join(dir, '*')]
+      begin
+        Gem::Uninstaller.new(spec.name, options).uninstall
+      rescue Gem::InstallError
+      end
     end
-    alert("Successfully uninstalled all gems in #{install_dir}")
+
+    alert "Uninstalled all gems in #{options[:install_dir]}"
   end
 
   def uninstall_specific
diff --git a/lib/rubygems/commands/unpack_command.rb b/lib/rubygems/commands/unpack_command.rb
index 7eefd32a6e..e60e7d90fd 100644
--- a/lib/rubygems/commands/unpack_command.rb
+++ b/lib/rubygems/commands/unpack_command.rb
@@ -34,6 +34,24 @@ class Gem::Commands::UnpackCommand < Gem::Command
     "--version '#{Gem::Requirement.default}'"
   end
 
+  def description
+    <<-EOF
+The unpack command allows you to examine the contents of a gem or modify
+them to help diagnose a bug.
+
+You can add the contents of the unpacked gem to the load path using the
+RUBYLIB environment variable or -I:
+
+  $ gem unpack my_gem
+  Unpacked gem: '.../my_gem-1.0'
+  [edit my_gem-1.0/lib/my_gem.rb]
+  $ ruby -Imy_gem-1.0/lib -S other_program
+
+You can repackage an unpacked gem using the build command.  See the build
+command help for an example.
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name} GEMNAME"
   end
diff --git a/lib/rubygems/commands/update_command.rb b/lib/rubygems/commands/update_command.rb
index 3a167361cf..77bf5edb45 100644
--- a/lib/rubygems/commands/update_command.rb
+++ b/lib/rubygems/commands/update_command.rb
@@ -52,6 +52,15 @@ class Gem::Commands::UpdateCommand < Gem::Command
     "--document --no-force --install-dir #{Gem.dir}"
   end
 
+  def description # :nodoc:
+    <<-EOF
+The update command will update your gems to the latest version.
+
+The update comamnd does not remove the previous version.  Use the cleanup
+command to remove old versions.
+    EOF
+  end
+
   def usage # :nodoc:
     "#{program_name} GEMNAME [GEMNAME ...]"
   end
diff --git a/lib/rubygems/commands/which_command.rb b/lib/rubygems/commands/which_command.rb
index 6495278a87..99b9085b2b 100644
--- a/lib/rubygems/commands/which_command.rb
+++ b/lib/rubygems/commands/which_command.rb
@@ -23,6 +23,17 @@ class Gem::Commands::WhichCommand < Gem::Command
     "--no-gems-first --no-all"
   end
 
+  def description # :nodoc:
+    <<-EOF
+The which command is like the shell which command and shows you where
+the file you wish to require lives.
+
+You can use the which command to help determine why you are requiring a
+version you did not expect or to look at the content of a file you are
+requiring to see why it does not behave as you expect.
+    EOF
+  end
+
   def execute
     found = false
 
diff --git a/lib/rubygems/commands/yank_command.rb b/lib/rubygems/commands/yank_command.rb
index df4142d395..2285bb4017 100644
--- a/lib/rubygems/commands/yank_command.rb
+++ b/lib/rubygems/commands/yank_command.rb
@@ -9,7 +9,21 @@ class Gem::Commands::YankCommand < Gem::Command
   include Gem::GemcutterUtilities
 
   def description # :nodoc:
-    'Remove a specific gem version release from RubyGems.org'
+    <<-EOF
+The yank command removes a gem you pushed to a server from the server's
+index.
+
+Note that if you push a gem to rubygems.org the yank command does not
+prevent other people from downloading the gem via the download link.
+
+Once you have pushed a gem several downloads will happen automatically
+via the webhooks.  If you accidentally pushed passwords or other sensitive
+data you will need to change them immediately and yank your gem.
+
+If you are yanking a gem due to intellectual property reasons contact
+http://help.rubygems.org for permanant removal.  Be sure to mention this
+as the reason for the removal request.
+    EOF
   end
 
   def arguments # :nodoc:
@@ -21,7 +35,7 @@ class Gem::Commands::YankCommand < Gem::Command
   end
 
   def initialize
-    super 'yank', description
+    super 'yank', 'Remove a pushed gem from the index'
 
     add_version_option("remove")
     add_platform_option("remove")