Merge pull request #8919 from rubygems/deivid-rodriguez/improve-cli-documentation

Improve documentation of `bundle doctor`, `bundle plugin`, and `bundle config`

Author: deivid-rodriguez

bundler/lib/bundler/cli.rb

@@ -520,11 +520,11 @@ def licenses
         Viz requires the ruby-graphviz gem (and its dependencies).
         The associated gems must also be installed via 'bundle install'.
       D
-      method_option :file, type: :string, default: "gem_graph", aliases: "-f", desc: "The name to use for the generated file. see format option"
-      method_option :format, type: :string, default: "png", aliases: "-F", desc: "This is output format option. Supported format is png, jpg, svg, dot ..."
-      method_option :requirements, type: :boolean, default: false, aliases: "-R", desc: "Set to show the version of each required dependency."
-      method_option :version, type: :boolean, default: false, aliases: "-v", desc: "Set to show each gem version."
-      method_option :without, type: :array, default: [], aliases: "-W", banner: "GROUP[ GROUP...]", desc: "Exclude gems that are part of the specified named group."
+      method_option :file, type: :string, default: "gem_graph", aliases: "-f", banner: "The name to use for the generated file. see format option"
+      method_option :format, type: :string, default: "png", aliases: "-F", banner: "This is output format option. Supported format is png, jpg, svg, dot ..."
+      method_option :requirements, type: :boolean, default: false, aliases: "-R", banner: "Set to show the version of each required dependency."
+      method_option :version, type: :boolean, default: false, aliases: "-v", banner: "Set to show each gem version."
+      method_option :without, type: :array, default: [], aliases: "-W", banner: "Exclude gems that are part of the specified named group."
       def viz
         SharedHelpers.major_deprecation 2, "The `viz` command has been renamed to `graph` and moved to a plugin. See https://github.com/rubygems/bundler-graph"
         require_relative "cli/viz"
@@ -533,19 +533,19 @@ def viz
     end
 
     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 set --global gem.coc true`."
-    method_option :edit, type: :string, aliases: "-e", required: false, banner: "EDITOR", lazy_default: [ENV["BUNDLER_EDITOR"], ENV["VISUAL"], ENV["EDITOR"]].find {|e| !e.nil? && !e.empty? }, desc: "Open generated gemspec in the specified editor (defaults to $EDITOR or $BUNDLER_EDITOR)"
-    method_option :ext, type: :string, desc: "Generate the boilerplate for C extension code.", enum: EXTENSIONS
-    method_option :git, type: :boolean, default: true, desc: "Initialize a git repo inside your library."
-    method_option :mit, type: :boolean, desc: "Generate an MIT license file. Set a default with `bundle config set --global gem.mit true`."
-    method_option :rubocop, type: :boolean, desc: "Add rubocop to the generated Rakefile and gemspec. Set a default with `bundle config set --global gem.rubocop true`."
-    method_option :changelog, type: :boolean, desc: "Generate changelog file. Set a default with `bundle config set --global gem.changelog true`."
+    method_option :exe, type: :boolean, default: false, aliases: ["--bin", "-b"], banner: "Generate a binary executable for your library."
+    method_option :coc, type: :boolean, banner: "Generate a code of conduct file. Set a default with `bundle config set --global gem.coc true`."
+    method_option :edit, type: :string, aliases: "-e", required: false, lazy_default: [ENV["BUNDLER_EDITOR"], ENV["VISUAL"], ENV["EDITOR"]].find {|e| !e.nil? && !e.empty? }, banner: "Open generated gemspec in the specified editor (defaults to $EDITOR or $BUNDLER_EDITOR)"
+    method_option :ext, type: :string, banner: "Generate the boilerplate for C extension code.", enum: EXTENSIONS
+    method_option :git, type: :boolean, default: true, banner: "Initialize a git repo inside your library."
+    method_option :mit, type: :boolean, banner: "Generate an MIT license file. Set a default with `bundle config set --global gem.mit true`."
+    method_option :rubocop, type: :boolean, banner: "Add rubocop to the generated Rakefile and gemspec. Set a default with `bundle config set --global gem.rubocop true`."
+    method_option :changelog, type: :boolean, banner: "Generate changelog file. Set a default with `bundle config set --global gem.changelog true`."
     method_option :test, type: :string, lazy_default: Bundler.settings["gem.test"] || "", aliases: "-t", banner: "Use the specified test framework for your library", enum: %w[rspec minitest test-unit], desc: "Generate a test directory for your library, either rspec, minitest or test-unit. Set a default with `bundle config set --global gem.test (rspec|minitest|test-unit)`."
-    method_option :ci, type: :string, lazy_default: Bundler.settings["gem.ci"] || "", enum: %w[github gitlab circle], desc: "Generate CI configuration, either GitHub Actions, GitLab CI or CircleCI. Set a default with `bundle config set --global gem.ci (github|gitlab|circle)`"
-    method_option :linter, type: :string, lazy_default: Bundler.settings["gem.linter"] || "", enum: %w[rubocop standard], desc: "Add a linter and code formatter, either RuboCop or Standard. Set a default with `bundle config set --global gem.linter (rubocop|standard)`"
+    method_option :ci, type: :string, lazy_default: Bundler.settings["gem.ci"] || "", enum: %w[github gitlab circle], banner: "Generate CI configuration, either GitHub Actions, GitLab CI or CircleCI. Set a default with `bundle config set --global gem.ci (github|gitlab|circle)`"
+    method_option :linter, type: :string, lazy_default: Bundler.settings["gem.linter"] || "", enum: %w[rubocop standard], banner: "Add a linter and code formatter, either RuboCop or Standard. Set a default with `bundle config set --global gem.linter (rubocop|standard)`"
     method_option :github_username, type: :string, default: Bundler.settings["gem.github_username"], banner: "Set your username on GitHub", desc: "Fill in GitHub username on README so that you don't have to do it manually. Set a default with `bundle config set --global gem.github_username <your_username>`."
-    method_option :bundle, type: :boolean, default: Bundler.settings["gem.bundle"], desc: "Automatically run `bundle install` after creation. Set a default with `bundle config set --global gem.bundle true`"
+    method_option :bundle, type: :boolean, default: Bundler.settings["gem.bundle"], banner: "Automatically run `bundle install` after creation. Set a default with `bundle config set --global gem.bundle true`"
 
     def gem(name)
       require_relative "cli/gem"

bundler/lib/bundler/man/bundle-add.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-ADD" "1" "July 2025" ""
+.TH "BUNDLE\-ADD" "1" "August 2025" ""
 .SH "NAME"
 \fBbundle\-add\fR \- Add gem to the Gemfile and run bundle install
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-binstubs.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-BINSTUBS" "1" "July 2025" ""
+.TH "BUNDLE\-BINSTUBS" "1" "August 2025" ""
 .SH "NAME"
 \fBbundle\-binstubs\fR \- Install the binstubs of the listed gems
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-cache.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-CACHE" "1" "July 2025" ""
+.TH "BUNDLE\-CACHE" "1" "August 2025" ""
 .SH "NAME"
 \fBbundle\-cache\fR \- Package your needed \fB\.gem\fR files into your application
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-check.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-CHECK" "1" "July 2025" ""
+.TH "BUNDLE\-CHECK" "1" "August 2025" ""
 .SH "NAME"
 \fBbundle\-check\fR \- Verifies if dependencies are satisfied by installed gems
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-clean.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-CLEAN" "1" "July 2025" ""
+.TH "BUNDLE\-CLEAN" "1" "August 2025" ""
 .SH "NAME"
 \fBbundle\-clean\fR \- Cleans up unused gems in your bundler directory
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-config.1

@@ -1,16 +1,16 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-CONFIG" "1" "July 2025" ""
+.TH "BUNDLE\-CONFIG" "1" "August 2025" ""
 .SH "NAME"
 \fBbundle\-config\fR \- Set bundler configuration options
 .SH "SYNOPSIS"
-\fBbundle config\fR list
+\fBbundle config\fR [list]
 .br
-\fBbundle config\fR [get] NAME
+\fBbundle config\fR [get [\-\-local|\-\-global]] NAME
 .br
-\fBbundle config\fR [set] NAME VALUE
+\fBbundle config\fR [set [\-\-local|\-\-global]] NAME VALUE
 .br
-\fBbundle config\fR unset NAME
+\fBbundle config\fR unset [\-\-local|\-\-global] NAME
 .SH "DESCRIPTION"
 This command allows you to interact with Bundler's configuration system\.
 .P
@@ -25,23 +25,40 @@ Global config (\fB~/\.bundle/config\fR)
 Bundler default config
 .IP "" 0
 .P
+Executing \fBbundle\fR with the \fBBUNDLE_IGNORE_CONFIG\fR environment variable set will cause it to ignore all configuration\.
+.SH "SUB\-COMMANDS"
+.SS "list (default command)"
 Executing \fBbundle config list\fR will print a list of all bundler configuration for the current bundle, and where that configuration was set\.
+.SS "get"
+Executing \fBbundle config get <name>\fR will print the value of that configuration setting, and all locations where it was set\.
 .P
-Executing \fBbundle config get <name>\fR will print the value of that configuration setting, and where it was set\.
-.P
-Executing \fBbundle config set <name> <value>\fR defaults to setting \fBlocal\fR configuration if executing from within a local application, otherwise it will set \fBglobal\fR configuration\. See \fB\-\-local\fR and \fB\-\-global\fR options below\.
+\fBOPTIONS\fR
+.TP
+\fB\-\-local\fR
+Get configuration from configuration file for the local application, namely, \fB<project_root>/\.bundle/config\fR, or \fB$BUNDLE_APP_CONFIG/config\fR if \fBBUNDLE_APP_CONFIG\fR is set\.
+.TP
+\fB\-\-global\fR
+Get configuration from configuration file global to all bundles executed as the current user, namely, from \fB~/\.bundle/config\fR\.
+.SS "set"
+Executing \fBbundle config set <name> <value>\fR defaults to setting \fBlocal\fR configuration if executing from within a local application, otherwise it will set \fBglobal\fR configuration\.
 .P
+\fBOPTIONS\fR
+.TP
+\fB\-\-local\fR
 Executing \fBbundle config set \-\-local <name> <value>\fR will set that configuration in the directory for the local application\. The configuration will be stored in \fB<project_root>/\.bundle/config\fR\. If \fBBUNDLE_APP_CONFIG\fR is set, the configuration will be stored in \fB$BUNDLE_APP_CONFIG/config\fR\.
-.P
+.TP
+\fB\-\-global\fR
 Executing \fBbundle config set \-\-global <name> <value>\fR will set that configuration to the value specified for all bundles executed as the current user\. The configuration will be stored in \fB~/\.bundle/config\fR\. If \fIname\fR already is set, \fIname\fR will be overridden and user will be warned\.
-.P
+.SS "unset"
 Executing \fBbundle config unset <name>\fR will delete the configuration in both local and global sources\.
 .P
-Executing \fBbundle config unset \-\-global <name>\fR will delete the configuration only from the user configuration\.
-.P
+\fBOPTIONS\fR
+.TP
+\fB\-\-local\fR
 Executing \fBbundle config unset \-\-local <name>\fR will delete the configuration only from the local application\.
-.P
-Executing bundle with the \fBBUNDLE_IGNORE_CONFIG\fR environment variable set will cause it to ignore all configuration\.
+.TP
+\fB\-\-global\fR
+Executing \fBbundle config unset \-\-global <name>\fR will delete the configuration only from the user configuration\.
 .SH "CONFIGURATION KEYS"
 Configuration keys in bundler have two forms: the canonical form and the environment variable form\.
 .P

bundler/lib/bundler/man/bundle-config.1.ronn

@@ -3,10 +3,10 @@ bundle-config(1) -- Set bundler configuration options
 
 ## SYNOPSIS
 
-`bundle config` list<br>
-`bundle config` [get] NAME<br>
-`bundle config` [set] NAME VALUE<br>
-`bundle config` unset NAME
+`bundle config` [list]<br>
+`bundle config` [get [--local|--global]] NAME<br>
+`bundle config` [set [--local|--global]] NAME VALUE<br>
+`bundle config` unset [--local|--global] NAME
 
 ## DESCRIPTION
 
@@ -19,38 +19,67 @@ Bundler loads configuration settings in this order:
 3. Global config (`~/.bundle/config`)
 4. Bundler default config
 
+Executing `bundle` with the `BUNDLE_IGNORE_CONFIG` environment variable set will
+cause it to ignore all configuration.
+
+## SUB-COMMANDS
+
+### list (default command)
+
 Executing `bundle config list` will print a list of all bundler
 configuration for the current bundle, and where that configuration
 was set.
 
+### get
+
 Executing `bundle config get <name>` will print the value of that configuration
-setting, and where it was set.
+setting, and all locations where it was set.
+
+**OPTIONS**
+
+* `--local`:
+  Get configuration from configuration file for the local application, namely,
+  `<project_root>/.bundle/config`, or `$BUNDLE_APP_CONFIG/config` if
+  `BUNDLE_APP_CONFIG` is set.
+
+* `--global`:
+  Get configuration from configuration file global to all bundles executed as
+  the current user, namely, from `~/.bundle/config`.
+
+### set
 
 Executing `bundle config set <name> <value>` defaults to setting `local`
 configuration if executing from within a local application, otherwise it will
-set `global` configuration. See `--local` and `--global` options below.
+set `global` configuration.
 
-Executing `bundle config set --local <name> <value>` will set that configuration
-in the directory for the local application. The configuration will be stored in
-`<project_root>/.bundle/config`. If `BUNDLE_APP_CONFIG` is set, the configuration
-will be stored in `$BUNDLE_APP_CONFIG/config`.
+**OPTIONS**
 
-Executing `bundle config set --global <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`. If <name> already
-is set, <name> will be overridden and user will be warned.
+* `--local`:
+  Executing `bundle config set --local <name> <value>` will set that configuration
+  in the directory for the local application. The configuration will be stored in
+  `<project_root>/.bundle/config`. If `BUNDLE_APP_CONFIG` is set, the configuration
+  will be stored in `$BUNDLE_APP_CONFIG/config`.
+
+* `--global`:
+  Executing `bundle config set --global <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`. If <name> already
+  is set, <name> will be overridden and user will be warned.
+
+### unset
 
 Executing `bundle config unset <name>` will delete the configuration in both
 local and global sources.
 
-Executing `bundle config unset --global <name>` will delete the configuration
-only from the user configuration.
+**OPTIONS**
 
-Executing `bundle config unset --local <name>` will delete the configuration
-only from the local application.
+* `--local`:
+  Executing `bundle config unset --local <name>` will delete the configuration
+  only from the local application.
 
-Executing bundle with the `BUNDLE_IGNORE_CONFIG` environment variable set will
-cause it to ignore all configuration.
+* `--global`:
+  Executing `bundle config unset --global <name>` will delete the configuration
+  only from the user configuration.
 
 ## CONFIGURATION KEYS
 

bundler/lib/bundler/man/bundle-console.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-CONSOLE" "1" "July 2025" ""
+.TH "BUNDLE\-CONSOLE" "1" "August 2025" ""
 .SH "NAME"
 \fBbundle\-console\fR \- Open an IRB session with the bundle pre\-loaded
 .SH "SYNOPSIS"

bundler/lib/bundler/man/bundle-doctor.1

@@ -1,12 +1,12 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "BUNDLE\-DOCTOR" "1" "July 2025" ""
+.TH "BUNDLE\-DOCTOR" "1" "August 2025" ""
 .SH "NAME"
 \fBbundle\-doctor\fR \- Checks the bundle for common problems
 .SH "SYNOPSIS"
 \fBbundle doctor [diagnose]\fR [\-\-quiet] [\-\-gemfile=GEMFILE] [\-\-ssl]
 .br
-\fBbundle doctor ssl\fR [\-\-host=HOST] [\-\-tls\-version=VERSION] [\-\-verify\-mode=MODE]
+\fBbundle doctor ssl\fR [\-\-host=HOST] [\-\-tls\-version=TLS\-VERSION] [\-\-verify\-mode=VERIFY\-MODE]
 .br
 \fBbundle doctor\fR help [COMMAND]
 .SH "DESCRIPTION"
@@ -57,12 +57,12 @@ Open a TLS connection and verify the outcome\.
 \fB\-\-host=HOST\fR
 Perform the diagnostic on HOST\. Defaults to \fBrubygems\.org\fR\.
 .TP
-\fB\-\-tls\-version=VERSION\fR
+\fB\-\-tls\-version=TLS\-VERSION\fR
 Specify the TLS version when opening the connection to HOST\.
 .IP
 Accepted values are: \fB1\.1\fR or \fB1\.2\fR\.
 .TP
-\fB\-\-verify\-mode=MODE\fR
+\fB\-\-verify\-mode=VERIFY\-MODE\fR
 Specify the TLS verify mode when opening the connection to HOST\. Defaults to \fBSSL_VERIFY_PEER\fR\.
 .IP
 Accepted values are: \fBCLIENT_ONCE\fR, \fBFAIL_IF_NO_PEER_CERT\fR, \fBNONE\fR, \fBPEER\fR\.