Merge pull request #8313 from rubygems/deivid-rodriguez/improve-documentation-of-command-flags

Normalize command flag documentation and make sure all flags are documented

Author: deivid-rodriguez

bundler/lib/bundler/cli.rb

@@ -217,7 +217,7 @@ def remove(*gems)
     method_option "full-index", type: :boolean, banner: "Fall back to using the single-file index of all gems"
     method_option "gemfile", type: :string, banner: "Use the specified gemfile instead of Gemfile"
     method_option "jobs", aliases: "-j", type: :numeric, banner: "Specify the number of jobs to run in parallel"
-    method_option "local", type: :boolean, banner:       "Do not attempt to fetch gems remotely and use the gem cache instead"
+    method_option "local", type: :boolean, banner: "Do not attempt to fetch gems remotely and use the gem cache instead"
     method_option "prefer-local", type: :boolean, banner: "Only attempt to fetch gems remotely if not present locally, even if newer versions are available remotely"
     method_option "no-cache", type: :boolean, banner: "Don't update the existing gem cache."
     method_option "redownload", type: :boolean, aliases: "--force", banner: "Force downloading every gem."
@@ -227,10 +227,8 @@ def remove(*gems)
     method_option "shebang", type: :string, banner: "Specify a different shebang executable name than the default (usually 'ruby')"
     method_option "standalone", type: :array, lazy_default: [], banner: "Make a bundle that can work without the Bundler runtime"
     method_option "system", type: :boolean, banner: "Install to the system location ($BUNDLE_PATH or $GEM_HOME) even if the bundle was previously installed somewhere else for this application"
-    method_option "trust-policy", alias: "P", type: :string, banner:       "Gem trust policy (like gem install -P). Must be one of " +
-                                                                           Bundler.rubygems.security_policy_keys.join("|")
-    method_option "target-rbconfig", type: :string, banner: "rbconfig.rb for the deployment target platform"
-
+    method_option "trust-policy", alias: "P", type: :string, banner: "Gem trust policy (like gem install -P). Must be one of #{Bundler.rubygems.security_policy_keys.join("|")}"
+    method_option "target-rbconfig", type: :string, banner: "Path to rbconfig.rb for the deployment target platform"
     method_option "without", type: :array, banner: "Exclude gems that are part of the specified named group."
     method_option "with", type: :array, banner: "Include gems that are part of the specified named group."
     def install
@@ -288,10 +286,8 @@ def update(*gems)
       Show lists the names and versions of all gems that are required by your Gemfile.
       Calling show with [GEM] will list the exact location of that gem on your machine.
     D
-    method_option "paths", type: :boolean,
-                           banner: "List the paths of all gems that are required by your Gemfile."
-    method_option "outdated", type: :boolean,
-                              banner: "Show verbose output including whether gems are outdated."
+    method_option "paths", type: :boolean, banner: "List the paths of all gems that are required by your Gemfile."
+    method_option "outdated", type: :boolean, banner: "Show verbose output including whether gems are outdated."
     def show(gem_name = nil)
       if ARGV.include?("--outdated")
         message = "the `--outdated` flag to `bundle show` was undocumented and will be removed without replacement"
@@ -400,9 +396,7 @@ def fund
     end
 
     desc "cache [OPTIONS]", "Locks and then caches all of the gems into vendor/cache"
-    method_option "all", type: :boolean,
-                         default: Bundler.feature_flag.cache_all?,
-                         banner: "Include all sources (including path and git)."
+    method_option "all", type: :boolean, default: Bundler.feature_flag.cache_all?, banner: "Include all sources (including path and git)."
     method_option "all-platforms", type: :boolean, banner: "Include gems for all platforms present in the lockfile, not only the current one"
     method_option "cache-path", type: :string, banner: "Specify a different cache path than the default (vendor/cache)."
     method_option "gemfile", type: :string, banner: "Use the specified gemfile instead of Gemfile"
@@ -440,8 +434,8 @@ def cache
     map aliases_for("cache")
 
     desc "exec [OPTIONS]", "Run the command in context of the bundle"
-    method_option :keep_file_descriptors, type: :boolean, default: true
-    method_option :gemfile, type: :string, required: false
+    method_option :keep_file_descriptors, type: :boolean, default: true, banner: "Passes all file descriptors to the new processes. Default is true, and setting it to false is deprecated"
+    method_option :gemfile, type: :string, required: false, banner: "Use the specified gemfile instead of Gemfile"
     long_desc <<-D
       Exec runs a command, providing it access to the gems in the bundle. While using
       bundle exec you can require and call the bundled gems as if they were installed
@@ -540,23 +534,15 @@ def viz
     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 :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 :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 :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 :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>`."
 
     def gem(name)

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

@@ -9,33 +9,36 @@
 Adds the named gem to the [\fBGemfile(5)\fR][Gemfile(5)] and run \fBbundle install\fR\. \fBbundle install\fR can be avoided by using the flag \fB\-\-skip\-install\fR\.
 .SH "OPTIONS"
 .TP
-\fB\-\-version\fR, \fB\-v\fR
+\fB\-\-version=VERSION\fR, \fB\-v=VERSION\fR
 Specify version requirements(s) for the added gem\.
 .TP
-\fB\-\-group\fR, \fB\-g\fR
+\fB\-\-group=GROUP\fR, \fB\-g=GROUP\fR
 Specify the group(s) for the added gem\. Multiple groups should be separated by commas\.
 .TP
-\fB\-\-source\fR, \fB\-s\fR
+\fB\-\-source=SOURCE\fR, \fB\-s=SOURCE\fR
 Specify the source for the added gem\.
 .TP
-\fB\-\-require\fR, \fB\-r\fR
+\fB\-\-require=REQUIRE\fR, \fB\-r=REQUIRE\fR
 Adds require path to gem\. Provide false, or a path as a string\.
 .TP
-\fB\-\-path\fR
+\fB\-\-path=PATH\fR
 Specify the file system path for the added gem\.
 .TP
-\fB\-\-git\fR
+\fB\-\-git=GIT\fR
 Specify the git source for the added gem\.
 .TP
-\fB\-\-github\fR
+\fB\-\-github=GITHUB\fR
 Specify the github source for the added gem\.
 .TP
-\fB\-\-branch\fR
+\fB\-\-branch=BRANCH\fR
 Specify the git branch for the added gem\.
 .TP
-\fB\-\-ref\fR
+\fB\-\-ref=REF\fR
 Specify the git ref for the added gem\.
 .TP
+\fB\-\-glob=GLOB\fR
+Specify the location of a dependency's \.gemspec, expanded within Ruby (single quotes recommended)\.
+.TP
 \fB\-\-quiet\fR
 Do not print progress information to the standard output\.
 .TP

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

@@ -14,33 +14,36 @@ Adds the named gem to the [`Gemfile(5)`][Gemfile(5)] and run `bundle install`.
 
 ## OPTIONS
 
-* `--version`, `-v`:
+* `--version=VERSION`, `-v=VERSION`:
   Specify version requirements(s) for the added gem.
 
-* `--group`, `-g`:
+* `--group=GROUP`, `-g=GROUP`:
   Specify the group(s) for the added gem. Multiple groups should be separated by commas.
 
-* `--source`, `-s`:
+* `--source=SOURCE`, `-s=SOURCE`:
   Specify the source for the added gem.
 
-* `--require`, `-r`:
+* `--require=REQUIRE`, `-r=REQUIRE`:
   Adds require path to gem. Provide false, or a path as a string.
 
-* `--path`:
+* `--path=PATH`:
   Specify the file system path for the added gem.
 
-* `--git`:
+* `--git=GIT`:
   Specify the git source for the added gem.
 
-* `--github`:
+* `--github=GITHUB`:
   Specify the github source for the added gem.
 
-* `--branch`:
+* `--branch=BRANCH`:
   Specify the git branch for the added gem.
 
-* `--ref`:
+* `--ref=REF`:
   Specify the git ref for the added gem.
 
+* `--glob=GLOB`:
+  Specify the location of a dependency's .gemspec, expanded within Ruby (single quotes recommended).
+
 * `--quiet`:
   Do not print progress information to the standard output.
 

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

@@ -4,7 +4,7 @@
 .SH "NAME"
 \fBbundle\-binstubs\fR \- Install the binstubs of the listed gems
 .SH "SYNOPSIS"
-\fBbundle binstubs\fR \fIGEM_NAME\fR [\-\-force] [\-\-path PATH] [\-\-standalone]
+\fBbundle binstubs\fR \fIGEM_NAME\fR [\-\-force] [\-\-path PATH] [\-\-standalone] [\-\-all\-platforms]
 .SH "DESCRIPTION"
 Binstubs are scripts that wrap around executables\. Bundler creates a small Ruby file (a binstub) that loads Bundler, runs the command, and puts it into \fBbin/\fR\. Binstubs are a shortcut\-or alternative\- to always using \fBbundle exec\fR\. This gives you a file that can be run directly, and one that will always run the correct gem version used by the application\.
 .P
@@ -16,15 +16,18 @@ This command generates binstubs for executables in \fBGEM_NAME\fR\. Binstubs are
 \fB\-\-force\fR
 Overwrite existing binstubs if they exist\.
 .TP
-\fB\-\-path\fR
+\fB\-\-path[=PATH]\fR
 The location to install the specified binstubs to\. This defaults to \fBbin\fR\.
 .TP
 \fB\-\-standalone\fR
 Makes binstubs that can work without depending on Rubygems or Bundler at runtime\.
 .TP
-\fB\-\-shebang\fR
+\fB\-\-shebang=SHEBANG\fR
 Specify a different shebang executable name than the default (default 'ruby')
 .TP
 \fB\-\-all\fR
 Create binstubs for all gems in the bundle\.
+.TP
+\fB\-\-all\-platforms\fR
+Install binstubs for all platforms\.
 

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

@@ -3,7 +3,7 @@ bundle-binstubs(1) -- Install the binstubs of the listed gems
 
 ## SYNOPSIS
 
-`bundle binstubs` <GEM_NAME> [--force] [--path PATH] [--standalone]
+`bundle binstubs` <GEM_NAME> [--force] [--path PATH] [--standalone] [--all-platforms]
 
 ## DESCRIPTION
 
@@ -27,15 +27,18 @@ Calling binstubs with [GEM [GEM]] will create binstubs for all given gems.
 * `--force`:
   Overwrite existing binstubs if they exist.
 
-* `--path`:
+* `--path[=PATH]`:
   The location to install the specified binstubs to. This defaults to `bin`.
 
 * `--standalone`:
   Makes binstubs that can work without depending on Rubygems or Bundler at
   runtime.
 
-* `--shebang`:
+* `--shebang=SHEBANG`:
   Specify a different shebang executable name than the default (default 'ruby')
 
 * `--all`:
   Create binstubs for all gems in the bundle.
+
+* `--all-platforms`:
+  Install binstubs for all platforms.

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

@@ -4,11 +4,39 @@
 .SH "NAME"
 \fBbundle\-cache\fR \- Package your needed \fB\.gem\fR files into your application
 .SH "SYNOPSIS"
-\fBbundle cache\fR
+\fBbundle cache\fR [\fIOPTIONS\fR]
 .P
 alias: \fBpackage\fR, \fBpack\fR
 .SH "DESCRIPTION"
 Copy all of the \fB\.gem\fR files needed to run the application into the \fBvendor/cache\fR directory\. In the future, when running \fBbundle install(1)\fR \fIbundle\-install\.1\.html\fR, use the gems in the cache in preference to the ones on \fBrubygems\.org\fR\.
+.SH "OPTIONS"
+.TP
+\fB\-\-all\fR
+Include all sources (including path and git)\.
+.TP
+\fB\-\-all\-platforms\fR
+Include gems for all platforms present in the lockfile, not only the current one\.
+.TP
+\fB\-\-cache\-path=CACHE\-PATH\fR
+Specify a different cache path than the default (vendor/cache)\.
+.TP
+\fB\-\-gemfile=GEMFILE\fR
+Use the specified gemfile instead of Gemfile\.
+.TP
+\fB\-\-no\-install\fR
+Don't install the gems, only update the cache\.
+.TP
+\fB\-\-no\-prune\fR
+Don't remove stale gems from the cache\.
+.TP
+\fB\-\-path=PATH\fR
+Specify a different path than the system default ($BUNDLE_PATH or $GEM_HOME)\.
+.TP
+\fB\-\-quiet\fR
+Only output warnings and errors\.
+.TP
+\fB\-\-frozen\fR
+Do not allow the Gemfile\.lock to be updated after this bundle cache operation's install\.
 .SH "GIT AND PATH GEMS"
 The \fBbundle cache\fR command can also package \fB:git\fR and \fB:path\fR dependencies besides \.gem files\. This needs to be explicitly enabled via the \fB\-\-all\fR option\. Once used, the \fB\-\-all\fR option will be remembered\.
 .SH "SUPPORT FOR MULTIPLE PLATFORMS"

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

@@ -3,7 +3,7 @@ bundle-cache(1) -- Package your needed `.gem` files into your application
 
 ## SYNOPSIS
 
-`bundle cache`
+`bundle cache` [*OPTIONS*]
 
 alias: `package`, `pack`
 
@@ -13,6 +13,35 @@ Copy all of the `.gem` files needed to run the application into the
 `vendor/cache` directory. In the future, when running [`bundle install(1)`](bundle-install.1.html),
 use the gems in the cache in preference to the ones on `rubygems.org`.
 
+## OPTIONS
+
+* `--all`:
+  Include all sources (including path and git).
+
+* `--all-platforms`:
+  Include gems for all platforms present in the lockfile, not only the current one.
+
+* `--cache-path=CACHE-PATH`:
+  Specify a different cache path than the default (vendor/cache).
+
+* `--gemfile=GEMFILE`:
+  Use the specified gemfile instead of Gemfile.
+
+* `--no-install`:
+  Don't install the gems, only update the cache.
+
+* `--no-prune`:
+  Don't remove stale gems from the cache.
+
+* `--path=PATH`:
+  Specify a different path than the system default ($BUNDLE_PATH or $GEM_HOME).
+
+* `--quiet`:
+  Only output warnings and errors.
+
+* `--frozen`:
+  Do not allow the Gemfile.lock to be updated after this bundle cache operation's install.
+
 ## GIT AND PATH GEMS
 
 The `bundle cache` command can also package `:git` and `:path` dependencies

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

@@ -16,9 +16,9 @@ If the lockfile needs to be updated then it will be resolved using the gems inst
 \fB\-\-dry\-run\fR
 Locks the [\fBGemfile(5)\fR][Gemfile(5)] before running the command\.
 .TP
-\fB\-\-gemfile\fR
+\fB\-\-gemfile=GEMFILE\fR
 Use the specified gemfile instead of the [\fBGemfile(5)\fR][Gemfile(5)]\.
 .TP
-\fB\-\-path\fR
+\fB\-\-path=PATH\fR
 Specify a different path than the system default (\fB$BUNDLE_PATH\fR or \fB$GEM_HOME\fR)\. Bundler will remember this value for future installs on this machine\.
 

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

@@ -22,8 +22,10 @@ installed on the local machine, if they satisfy the requirements.
 
 * `--dry-run`:
   Locks the [`Gemfile(5)`][Gemfile(5)] before running the command.
-* `--gemfile`:
+
+* `--gemfile=GEMFILE`:
   Use the specified gemfile instead of the [`Gemfile(5)`][Gemfile(5)].
-* `--path`:
+
+* `--path=PATH`:
   Specify a different path than the system default (`$BUNDLE_PATH` or `$GEM_HOME`).
   Bundler will remember this value for future installs on this machine.

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

@@ -25,6 +25,6 @@ Missing dependencies
 \fB\-\-quiet\fR
 Only output warnings and errors\.
 .TP
-\fB\-\-gemfile=<gemfile>\fR
+\fB\-\-gemfile=GEMFILE\fR
 The location of the Gemfile(5) which Bundler should use\. This defaults to a Gemfile(5) in the current working directory\. In general, Bundler will assume that the location of the Gemfile(5) is also the project's root and will try to find \fBGemfile\.lock\fR and \fBvendor/cache\fR relative to this location\.