cmd/uses & cmd/deps: update help/man pages

- add clarification about precedence of command options
- reword some options for readability
- clarify the defaults in `brew deps`

Library/Homebrew/cmd/deps.rb

@@ -15,7 +15,10 @@ def self.deps_args
       description <<~EOS
         Show dependencies for <formula>. Additional options specific to <formula>
         may be appended to the command. When given multiple formula arguments,
-        show the intersection of dependencies for each formula.
+        show the intersection of dependencies for each formula. By default, `deps`
+        shows all required and recommended dependencies.
+
+        Note: `--missing` and `--skip-recommended` have precedence over `--include-*`.
       EOS
       switch "-n", "--topological",
              description: "Sort dependencies in topological order."

Library/Homebrew/cmd/uses.rb

@@ -22,6 +22,8 @@ def self.uses_args
         of <formula>. When given multiple formula arguments, show the intersection
         of formulae that use <formula>. By default, `uses` shows all formulae and casks that
         specify <formula> as a required or recommended dependency for their stable builds.
+
+        Note: `--missing` and `--skip-recommended` have precedence over `--include-*`.
       EOS
       switch "--recursive",
              description: "Resolve more than one level of dependencies."
@@ -33,13 +35,13 @@ def self.uses_args
              description: "Evaluate all available formulae and casks, whether installed or not, to show " \
                           "their dependents."
       switch "--include-build",
-             description: "Include all formulae that specify <formula> as `:build` type dependency."
+             description: "Include formulae that specify <formula> as a `:build` dependency."
       switch "--include-test",
-             description: "Include all formulae that specify <formula> as `:test` type dependency."
+             description: "Include formulae that specify <formula> as a `:test` dependency."
       switch "--include-optional",
-             description: "Include all formulae that specify <formula> as `:optional` type dependency."
+             description: "Include formulae that specify <formula> as an `:optional` dependency."
       switch "--skip-recommended",
-             description: "Skip all formulae that specify <formula> as `:recommended` type dependency."
+             description: "Skip all formulae that specify <formula> as a `:recommended` dependency."
       switch "--formula", "--formulae",
              description: "Include only formulae."
       switch "--cask", "--casks",

completions/fish/brew.fish

@@ -1700,14 +1700,14 @@ __fish_brew_complete_arg 'uses' -l debug -d 'Display any debugging information'
 __fish_brew_complete_arg 'uses' -l eval-all -d 'Evaluate all available formulae and casks, whether installed or not, to show their dependents'
 __fish_brew_complete_arg 'uses' -l formula -d 'Include only formulae'
 __fish_brew_complete_arg 'uses' -l help -d 'Show this message'
-__fish_brew_complete_arg 'uses' -l include-build -d 'Include all formulae that specify formula as `:build` type dependency'
-__fish_brew_complete_arg 'uses' -l include-optional -d 'Include all formulae that specify formula as `:optional` type dependency'
-__fish_brew_complete_arg 'uses' -l include-test -d 'Include all formulae that specify formula as `:test` type dependency'
+__fish_brew_complete_arg 'uses' -l include-build -d 'Include formulae that specify formula as a `:build` dependency'
+__fish_brew_complete_arg 'uses' -l include-optional -d 'Include formulae that specify formula as an `:optional` dependency'
+__fish_brew_complete_arg 'uses' -l include-test -d 'Include formulae that specify formula as a `:test` dependency'
 __fish_brew_complete_arg 'uses' -l installed -d 'Only list formulae and casks that are currently installed'
 __fish_brew_complete_arg 'uses' -l missing -d 'Only list formulae and casks that are not currently installed'
 __fish_brew_complete_arg 'uses' -l quiet -d 'Make some output more quiet'
 __fish_brew_complete_arg 'uses' -l recursive -d 'Resolve more than one level of dependencies'
-__fish_brew_complete_arg 'uses' -l skip-recommended -d 'Skip all formulae that specify formula as `:recommended` type dependency'
+__fish_brew_complete_arg 'uses' -l skip-recommended -d 'Skip all formulae that specify formula as a `:recommended` dependency'
 __fish_brew_complete_arg 'uses' -l verbose -d 'Make some output more verbose'
 __fish_brew_complete_arg 'uses; and not __fish_seen_argument -l cask -l casks' -a '(__fish_brew_suggest_formulae_all)'
 

completions/zsh/_brew

@@ -2092,14 +2092,14 @@ _brew_uses() {
     '--debug[Display any debugging information]' \
     '--eval-all[Evaluate all available formulae and casks, whether installed or not, to show their dependents]' \
     '--help[Show this message]' \
-    '--include-build[Include all formulae that specify formula as `:build` type dependency]' \
-    '--include-optional[Include all formulae that specify formula as `:optional` type dependency]' \
-    '--include-test[Include all formulae that specify formula as `:test` type dependency]' \
+    '--include-build[Include formulae that specify formula as a `:build` dependency]' \
+    '--include-optional[Include formulae that specify formula as an `:optional` dependency]' \
+    '--include-test[Include formulae that specify formula as a `:test` dependency]' \
     '(--all --missing)--installed[Only list formulae and casks that are currently installed]' \
     '(--installed)--missing[Only list formulae and casks that are not currently installed]' \
     '--quiet[Make some output more quiet]' \
     '--recursive[Resolve more than one level of dependencies]' \
-    '--skip-recommended[Skip all formulae that specify formula as `:recommended` type dependency]' \
+    '--skip-recommended[Skip all formulae that specify formula as a `:recommended` dependency]' \
     '--verbose[Make some output more verbose]' \
     - formula \
     '(--cask)--formula[Include only formulae]' \

docs/Manpage.md

@@ -139,7 +139,10 @@ a bug report, you will be required to provide this information.
 
 Show dependencies for *`formula`*. Additional options specific to *`formula`*
 may be appended to the command. When given multiple formula arguments,
-show the intersection of dependencies for each formula.
+show the intersection of dependencies for each formula. By default, `deps`
+shows all required and recommended dependencies.
+
+Note: `--missing` and `--skip-recommended` have precedence over `--include-*`.
 
 * `-n`, `--topological`:
   Sort dependencies in topological order.
@@ -819,6 +822,8 @@ of *`formula`*. When given multiple formula arguments, show the intersection
 of formulae that use *`formula`*. By default, `uses` shows all formulae and casks that
 specify *`formula`* as a required or recommended dependency for their stable builds.
 
+Note: `--missing` and `--skip-recommended` have precedence over `--include-*`.
+
 * `--recursive`:
   Resolve more than one level of dependencies.
 * `--installed`:
@@ -828,13 +833,13 @@ specify *`formula`* as a required or recommended dependency for their stable bui
 * `--eval-all`:
   Evaluate all available formulae and casks, whether installed or not, to show their dependents.
 * `--include-build`:
-  Include all formulae that specify *`formula`* as `:build` type dependency.
+  Include formulae that specify *`formula`* as a `:build` dependency.
 * `--include-test`:
-  Include all formulae that specify *`formula`* as `:test` type dependency.
+  Include formulae that specify *`formula`* as a `:test` dependency.
 * `--include-optional`:
-  Include all formulae that specify *`formula`* as `:optional` type dependency.
+  Include formulae that specify *`formula`* as an `:optional` dependency.
 * `--skip-recommended`:
-  Skip all formulae that specify *`formula`* as `:recommended` type dependency.
+  Skip all formulae that specify *`formula`* as a `:recommended` dependency.
 * `--formula`:
   Include only formulae.
 * `--cask`:

manpages/brew.1

@@ -155,7 +155,10 @@ Control whether Homebrew automatically links external tap shell completion files
 Show Homebrew and system configuration info useful for debugging\. If you file a bug report, you will be required to provide this information\.
 .
 .SS "\fBdeps\fR [\fIoptions\fR] [\fIformula\fR|\fIcask\fR \.\.\.]"
-Show dependencies for \fIformula\fR\. Additional options specific to \fIformula\fR may be appended to the command\. When given multiple formula arguments, show the intersection of dependencies for each formula\.
+Show dependencies for \fIformula\fR\. Additional options specific to \fIformula\fR may be appended to the command\. When given multiple formula arguments, show the intersection of dependencies for each formula\. By default, \fBdeps\fR shows all required and recommended dependencies\.
+.
+.P
+Note: \fB\-\-missing\fR and \fB\-\-skip\-recommended\fR have precedence over \fB\-\-include\-*\fR\.
 .
 .TP
 \fB\-n\fR, \fB\-\-topological\fR
@@ -1149,6 +1152,9 @@ Disable/enable quarantining of downloads (default: enabled)\.
 .SS "\fBuses\fR [\fIoptions\fR] \fIformula\fR [\.\.\.]"
 Show formulae and casks that specify \fIformula\fR as a dependency; that is, show dependents of \fIformula\fR\. When given multiple formula arguments, show the intersection of formulae that use \fIformula\fR\. By default, \fBuses\fR shows all formulae and casks that specify \fIformula\fR as a required or recommended dependency for their stable builds\.
 .
+.P
+Note: \fB\-\-missing\fR and \fB\-\-skip\-recommended\fR have precedence over \fB\-\-include\-*\fR\.
+.
 .TP
 \fB\-\-recursive\fR
 Resolve more than one level of dependencies\.
@@ -1167,19 +1173,19 @@ Evaluate all available formulae and casks, whether installed or not, to show the
 .
 .TP
 \fB\-\-include\-build\fR
-Include all formulae that specify \fIformula\fR as \fB:build\fR type dependency\.
+Include formulae that specify \fIformula\fR as a \fB:build\fR dependency\.
 .
 .TP
 \fB\-\-include\-test\fR
-Include all formulae that specify \fIformula\fR as \fB:test\fR type dependency\.
+Include formulae that specify \fIformula\fR as a \fB:test\fR dependency\.
 .
 .TP
 \fB\-\-include\-optional\fR
-Include all formulae that specify \fIformula\fR as \fB:optional\fR type dependency\.
+Include formulae that specify \fIformula\fR as an \fB:optional\fR dependency\.
 .
 .TP
 \fB\-\-skip\-recommended\fR
-Skip all formulae that specify \fIformula\fR as \fB:recommended\fR type dependency\.
+Skip all formulae that specify \fIformula\fR as a \fB:recommended\fR dependency\.
 .
 .TP
 \fB\-\-formula\fR