Auto merge of #5979 - bundler:seg-pretty-bundle-help, r=indirect

[CLI] Prettify the output in cli_help

### What was the end-user problem that led to this PR?

The problem was the new help output for `bundle` was very verbose and unorganized, making it look a bit like work vomit.

### What was your diagnosis of the problem?

My diagnosis was we should

Closes https://github.com/bundler/bundler/issues/5963.

### What is your fix for the problem, implemented in this PR?

My fix prints the full version info, as well as grouping the commands into `primary` and `utility` as done in the man pages.

### Why did you choose this fix out of the possible options?

I chose this fix because it makes the output pleasing to visually parse.

```
$ bundle
Bundler version 1.15.4 (2017-08-25 commit 3203fdd2a)

Bundler commands:

  Primary commands:
    bundle install [OPTIONS]    # Install the current environment to the system
    bundle update [OPTIONS]     # Update the current environment
    bundle package [OPTIONS]    # Locks and then caches all of the gems into vendor/cache
    bundle exec [OPTIONS]       # Run the command in context of the bundle
    bundle config NAME [VALUE]  # Retrieve or set a configuration value
    bundle help [COMMAND]       # Describe available commands or one specific command

  Utilities:
    bundle add GEM VERSION         # Add gem to Gemfile and run bundle install
    bundle binstubs GEM [OPTIONS]  # Install the binstubs of the listed gem
    bundle check [OPTIONS]         # Checks if the dependencies listed in Gemfile are satisfied by currently installed gems
    bundle console [GROUP]         # Opens an IRB session with the bundle pre-loaded
    bundle doctor [OPTIONS]        # Checks the bundle for common problems
    bundle env                     # Print information about the environment Bundler is running under
    bundle gem NAME [OPTIONS]      # Creates a skeleton for creating a rubygem
    bundle info GEM [OPTIONS]      # Show information for the given gem
    bundle init [OPTIONS]          # Generates a Gemfile into the current working directory
    bundle issue                   # Learn how to report an issue in Bundler
    bundle licenses                # Prints the license of all gems in the bundle
    bundle lock                    # Creates a lockfile without installing
    bundle open GEM                # Opens the source directory of the given bundled gem
    bundle outdated GEM [OPTIONS]  # List installed gems with newer versions available
    bundle platform [OPTIONS]      # Displays platform compatibility information
    bundle plugin                  # Manage the bundler plugins
    bundle pristine [GEMS...]      # Restores installed gems to pristine condition from files located in the gem cache. Gem installed from a git reposit...
    bundle show GEM [OPTIONS]      # Shows all gems that are part of the bundle, or the path to a given gem
    bundle version                 # Prints the bundler's version information

Options:
      [--no-color]                 # Disable colorization in output
  -r, [--retry=NUM]                # Specify the number of times you wish to attempt network commands
  -V, [--verbose], [--no-verbose]  # Enable verbose output mode
```

3 files changed, 55 insertions, 19 deletions

diff --git a/lib/bundler/cli.rb b/lib/bundler/cli.rb
index 97ee5beca0..05e1851c18 100644
--- a/lib/bundler/cli.rb
+++ b/lib/bundler/cli.rb
@@ -7,6 +7,8 @@ module Bundler
   class CLI < Thor
     require "bundler/cli/common"
 
+    package_name "Bundler"
+
     AUTO_INSTALL_CMDS = %w[show binstubs outdated exec open console licenses clean].freeze
     PARSEABLE_COMMANDS = %w[
       check config help exec platform show version
@@ -71,7 +73,26 @@ module Bundler
     def cli_help
       version
       Bundler.ui.info "\n"
-      self.class.help(shell)
+
+      primary_commands = ["install", "update",
+                          Bundler.feature_flag.cache_command_is_package? ? "cache" : "package",
+                          "exec", "config", "help"]
+
+      list = self.class.printable_commands(true)
+      by_name = list.group_by {|name, _message| name.match(/^bundle (\w+)/)[1] }
+      utilities = by_name.keys.sort - primary_commands
+      primary_commands.map! {|name| (by_name[name] || raise("no primary command #{name}")).first }
+      utilities.map! {|name| by_name[name].first }
+
+      shell.say "Bundler commands:\n\n"
+
+      shell.say "  Primary commands:\n"
+      shell.print_table(primary_commands, :indent => 4, :truncate => true)
+      shell.say
+      shell.say "  Utilities:\n"
+      shell.print_table(utilities, :indent => 4, :truncate => true)
+      shell.say
+      self.class.send(:class_options_help, shell)
     end
     default_task(Bundler.feature_flag.default_cli_command)
 
@@ -437,11 +458,12 @@ module Bundler
 
     desc "version", "Prints the bundler's version information"
     def version
-      if ARGV.include?("version")
+      cli_help = current_command.name == "cli_help"
+      if cli_help || ARGV.include?("version")
         build_info = " (#{BuildMetadata.built_at} commit #{BuildMetadata.git_commit_sha})"
       end
 
-      if Bundler.feature_flag.print_only_version_number?
+      if !cli_help && Bundler.feature_flag.print_only_version_number?
         Bundler.ui.info "#{Bundler::VERSION}#{build_info}"
       else
         Bundler.ui.info "Bundler version #{Bundler::VERSION}#{build_info}"
@@ -463,7 +485,7 @@ module Bundler
       end
     end
 
-    desc "viz [OPTIONS]", "Generates a visual dependency graph"
+    desc "viz [OPTIONS]", "Generates a visual dependency graph", :hide => true
     long_desc <<-D
       Viz generates a PNG file of the current Gemfile as a dependency graph.
       Viz requires the ruby-graphviz gem (and its dependencies).
@@ -481,7 +503,7 @@ module Bundler
 
     old_gem = instance_method(:gem)
 
-    desc "gem GEM [OPTIONS]", "Creates a skeleton for creating a rubygem"
+    desc "gem NAME [OPTIONS]", "Creates a skeleton for creating a rubygem"
     method_option :exe, :type => :boolean, :default => false, :aliases => ["--bin", "-b"], :desc => "Generate a binary executable for your library."
     method_option :coc, :type => :boolean, :desc => "Generate a code of conduct file. Set a default with `bundle config gem.coc true`."
     method_option :edit, :type => :string, :aliases => "-e", :required => false, :banner => "EDITOR",
@@ -520,7 +542,7 @@ module Bundler
       File.expand_path(File.join(File.dirname(__FILE__), "templates"))
     end
 
-    desc "clean [OPTIONS]", "Cleans up unused gems in your bundler directory"
+    desc "clean [OPTIONS]", "Cleans up unused gems in your bundler directory", :hide => true
     method_option "dry-run", :type => :boolean, :default => false, :banner =>
       "Only print out changes, do not clean gems"
     method_option "force", :type => :boolean, :default => false, :banner =>
@@ -538,7 +560,7 @@ module Bundler
       Platform.new(options).run
     end
 
-    desc "inject GEM VERSION", "Add the named gem, with version requirements, to the resolved Gemfile"
+    desc "inject GEM VERSION", "Add the named gem, with version requirements, to the resolved Gemfile", :hide => true
     method_option "source", :type => :string, :banner =>
      "Install gem from the given source"
     method_option "group", :type => :string, :banner =>
@@ -618,7 +640,7 @@ module Bundler
 
     if Bundler.feature_flag.plugins?
       require "bundler/cli/plugin"
-      desc "plugin SUBCOMMAND ...ARGS", "Manage the bundler plugins"
+      desc "plugin", "Manage the bundler plugins"
       subcommand "plugin", Plugin
     end
 
@@ -668,16 +690,20 @@ module Bundler
       end
     end
 
+    def current_command
+      _, _, config = @_initializer
+      config[:current_command]
+    end
+
     def print_command
       return unless Bundler.ui.debug?
-      _, _, config = @_initializer
-      current_command = config[:current_command]
-      command_name = current_command.name
+      cmd = current_command
+      command_name = cmd.name
       return if PARSEABLE_COMMANDS.include?(command_name)
       command = ["bundle", command_name] + args
       options_to_print = options.dup
       options_to_print.delete_if do |k, v|
-        next unless o = current_command.options[k]
+        next unless o = cmd.options[k]
         o.default == v
       end
       command << Thor::Options.to_switches(options_to_print.sort_by(&:first)).strip
@@ -688,8 +714,6 @@ module Bundler
     def warn_on_outdated_bundler
       return if Bundler.settings[:disable_version_check]
 
-      _, _, config = @_initializer
-      current_command = config[:current_command]
       command_name = current_command.name
       return if PARSEABLE_COMMANDS.include?(command_name)
 
@@ -708,8 +732,8 @@ module Bundler
 
       installation = "To install the latest version, run `gem install bundler#{" --pre" if latest.prerelease?}`"
       if latest_installed && latest_installed > current
-        suggestion = "To update to the most recent installed version, run `bundle update --bundler`"
-        suggestion = "#{installation}\n#{suggestion}" if latest_installed > latest
+        suggestion = "To update to the most recent installed version (#{latest_installed}), run `bundle update --bundler`"
+        suggestion = "#{installation}\n#{suggestion}" if latest_installed < latest
       else
         suggestion = installation
       end
diff --git a/spec/bundler/cli_spec.rb b/spec/bundler/cli_spec.rb
index fd4820b67f..5b48808e44 100644
--- a/spec/bundler/cli_spec.rb
+++ b/spec/bundler/cli_spec.rb
@@ -26,6 +26,18 @@ RSpec.describe "bundle executable" do
     expect(out).to eq("Hello, world")
   end
 
+  context "with no arguments" do
+    it "prints a concise help message", :bundler => "2" do
+      bundle! ""
+      expect(last_command.stderr).to be_empty
+      expect(last_command.stdout).to include("Bundler version #{Bundler::VERSION}").
+        and include("\n\nBundler commands:\n\n").
+        and include("\n\n  Primary commands:\n").
+        and include("\n\n  Utilities:\n").
+        and include("\n\nOptions:\n")
+    end
+  end
+
   context "when ENV['BUNDLE_GEMFILE'] is set to an empty string" do
     it "ignores it" do
       gemfile bundled_app("Gemfile"), <<-G
@@ -107,7 +119,7 @@ RSpec.describe "bundle executable" do
     end
 
     context "when the latest version is greater than the current version" do
-      let(:latest_version) { "2.0" }
+      let(:latest_version) { "222.0" }
       it "prints the version warning" do
         bundle "fail"
         expect(last_command.stdout).to start_with(<<-EOS.strip)
@@ -132,7 +144,7 @@ To install the latest version, run `gem install bundler`
       end
 
       context "and is a pre-release" do
-        let(:latest_version) { "2.0.0.pre.4" }
+        let(:latest_version) { "222.0.0.pre.4" }
         it "prints the version warning" do
           bundle "fail"
           expect(last_command.stdout).to start_with(<<-EOS.strip)
diff --git a/spec/commands/newgem_spec.rb b/spec/commands/newgem_spec.rb
index 8d851f28a4..259c73a903 100644
--- a/spec/commands/newgem_spec.rb
+++ b/spec/commands/newgem_spec.rb
@@ -799,7 +799,7 @@ RSpec.describe "bundle gem" do
       bundle "gem foo bar baz"
       expect(last_command.bundler_err).to eq(<<-E.strip)
 ERROR: "bundle gem" was called with arguments ["foo", "bar", "baz"]
-Usage: "bundle gem GEM [OPTIONS]"
+Usage: "bundle gem NAME [OPTIONS]"
       E
     end
   end