rubygems-update 2.1.0.rc.1 → 2.1.0.rc.2

data/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
 

data/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

data/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

data/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.
 

data/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

data/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

data/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

data/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})"

data/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 => []

data/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

data/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

data/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
 

data/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
 

data/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

data/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

data/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

data/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

data/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

data/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