Document behavior of `deps` and `uses` when given multiple arguments

2 files changed, 12 insertions, 8 deletions

diff --git a/Library/Contributions/manpages/brew.1.md b/Library/Contributions/manpages/brew.1.md
index e27fa8f27..3bfd19e99 100644
--- a/Library/Contributions/manpages/brew.1.md
+++ b/Library/Contributions/manpages/brew.1.md
@@ -84,8 +84,10 @@ Note that these flags should only appear after a command.
     The options `--set-name` and `--set-version` each take an argument and allow
     you to explicitly set the name and version of the package you are creating.
 
-  * `deps [--1] [-n] [--tree] [--all] [--installed]` <formula>:
-    Show <formula>'s dependencies.
+  * `deps [--1] [-n] [--tree] [--all] [--installed]` <formulae>:
+    Show dependencies for <formulae>. When given multiple formula arguments,
+    show the intersection of dependencies for <formulae>, except when passed
+    `--tree`, `--all`, or `--installed`.
 
     If `--1` is passed, only show dependencies one level down, instead of
     recursing.
@@ -355,8 +357,10 @@ Note that these flags should only appear after a command.
     If <formulae> are given, upgrade only the specified brews (but do so even
     if they are pinned; see `pin`, `unpin`).
 
-  * `uses [--installed] [--recursive] [--devel|--HEAD]` <formula>:
-    Show the formulae that specify <formula> as a dependency.
+  * `uses [--installed] [--recursive] [--devel|--HEAD]` <formulae>:
+    Show the formulae that specify <formulae> as a dependency. When given
+    multiple formula arguments, show the intersection of formulae that use
+    <formulae>.
 
     Use `--recursive` to resolve more than one level of dependencies.
 
diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1
index f0fa7736f..756b43106 100644
--- a/share/man/man1/brew.1
+++ b/share/man/man1/brew.1
@@ -91,8 +91,8 @@ If \fB\-\-no\-fetch\fR is passed, Homebrew will not download \fIURL\fR to the ca
 The options \fB\-\-set\-name\fR and \fB\-\-set\-version\fR each take an argument and allow you to explicitly set the name and version of the package you are creating\.
 .
 .TP
-\fBdeps [\-\-1] [\-n] [\-\-tree] [\-\-all] [\-\-installed]\fR \fIformula\fR
-Show \fIformula\fR\'s dependencies\.
+\fBdeps [\-\-1] [\-n] [\-\-tree] [\-\-all] [\-\-installed]\fR \fIformulae\fR
+Show dependencies for \fIformulae\fR\. When given multiple formula arguments, show the intersection of dependencies for \fIformulae\fR, except when passed \fB\-\-tree\fR, \fB\-\-all\fR, or \fB\-\-installed\fR\.
 .
 .IP
 If \fB\-\-1\fR is passed, only show dependencies one level down, instead of recursing\.
@@ -381,8 +381,8 @@ Options for the \fBinstall\fR command are also valid here\.
 If \fIformulae\fR are given, upgrade only the specified brews (but do so even if they are pinned; see \fBpin\fR, \fBunpin\fR)\.
 .
 .TP
-\fBuses [\-\-installed] [\-\-recursive] [\-\-devel|\-\-HEAD]\fR \fIformula\fR
-Show the formulae that specify \fIformula\fR as a dependency\.
+\fBuses [\-\-installed] [\-\-recursive] [\-\-devel|\-\-HEAD]\fR \fIformulae\fR
+Show the formulae that specify \fIformulae\fR as a dependency\. When given multiple formula arguments, show the intersection of formulae that use \fIformulae\fR\.
 .
 .IP
 Use \fB\-\-recursive\fR to resolve more than one level of dependencies\.