From 6fdcab5abcffbbb0a3a734e1db7d7afe6cac753a Mon Sep 17 00:00:00 2001 From: Martin Afanasjew Date: Sun, 1 May 2016 17:09:42 +0200 Subject: deps: split and clarify documentation `brew deps` has three different modes of operation that were not easy to infer from the existing documentation. Split the help text into three parts to make this clearer. This also improves on the confusion when options were silently ignored because they don't apply to a certain mode of operation. Those are: 1. List the shared dependencies (either intersection or union) of explicitly named formulae with options for traversal depth/order. 2. Output separate trees of explicitly listed or all installed formulae. 3. List all available/installed formulae and their direct dependencies with one line per formula formatted as `: `. Closes #137. Closes #179. Signed-off-by: Martin Afanasjew --- Library/Homebrew/cmd/deps.rb | 29 +++++++++++++++++++++-------- share/doc/homebrew/brew.1.html | 25 +++++++++++++++++-------- share/man/man1/brew.1 | 23 +++++++++++++++++------ 3 files changed, 55 insertions(+), 22 deletions(-) diff --git a/Library/Homebrew/cmd/deps.rb b/Library/Homebrew/cmd/deps.rb index 7a6b0a1e5..4c5dbb932 100644 --- a/Library/Homebrew/cmd/deps.rb +++ b/Library/Homebrew/cmd/deps.rb @@ -1,7 +1,6 @@ -#: * `deps` [`--1`] [`-n`] [`--union`] [`--tree`] [`--all`] [`--installed`] [`--include-build`] [`--include-optional`] [`--skip-recommended`] : +#: * `deps` [`--1`] [`-n`] [`--union`] [`--installed`] [`--include-build`] [`--include-optional`] [`--skip-recommended`] : #: Show dependencies for . When given multiple formula arguments, -#: show the intersection of dependencies for , except when passed -#: `--tree`, `--all`, or `--installed`. +#: show the intersection of dependencies for . #: #: If `--1` is passed, only show dependencies one level down, instead of #: recursing. @@ -11,16 +10,30 @@ #: If `--union` is passed, show the union of dependencies for , #: instead of the intersection. #: -#: If `--tree` is passed, show dependencies as a tree. -#: -#: If `--all` is passed, show dependencies for all formulae. -#: -#: If `--installed` is passed, show dependencies for all installed formulae. +#: If `--installed` is passed, only list those dependencies that are +#: currently installed. #: #: By default, `deps` shows required and recommended dependencies for #: . To include the `:build` type dependencies, pass `--include-build`. #: Similarly, pass `--include-optional` to include `:optional` dependencies. #: To skip `:recommended` type dependencies, pass `--skip-recommended`. +#: +#: * `deps` `--tree` [] (|`--installed`): +#: Show dependencies as a tree. When given multiple formula arguments, output +#: individual trees for every formula. +#: +#: If `--installed` is passed, output a tree for every installed formula. +#: +#: The placeholder is any combination of options `--include-build`, +#: `--include-optional`, and `--skip-recommended` as documented above. +#: +#: * `deps` [] (`--installed`|`--all`): +#: Show dependencies for installed or all available formulae. Every line of +#: output starts with the formula name, followed by a colon and all direct +#: dependencies of that formula. +#: +#: The placeholder is any combination of options `--include-build`, +#: `--include-optional`, and `--skip-recommended` as documented above. # encoding: UTF-8 require "formula" diff --git a/share/doc/homebrew/brew.1.html b/share/doc/homebrew/brew.1.html index 4626588be..daf613eb3 100644 --- a/share/doc/homebrew/brew.1.html +++ b/share/doc/homebrew/brew.1.html @@ -90,9 +90,8 @@ will thus not add the SHA256 to the formula for you.

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] [--union] [--tree] [--all] [--installed] [--include-build] [--include-optional] [--skip-recommended] formulae

Show dependencies for formulae. When given multiple formula arguments, -show the intersection of dependencies for formulae, except when passed ---tree, --all, or --installed.

+
deps [--1] [-n] [--union] [--installed] [--include-build] [--include-optional] [--skip-recommended] formulae

Show dependencies for formulae. When given multiple formula arguments, +show the intersection of dependencies for formulae.

If --1 is passed, only show dependencies one level down, instead of recursing.

@@ -102,16 +101,26 @@ recursing.

If --union is passed, show the union of dependencies for formulae, instead of the intersection.

-

If --tree is passed, show dependencies as a tree.

- -

If --all is passed, show dependencies for all formulae.

- -

If --installed is passed, show dependencies for all installed formulae.

+

If --installed is passed, only list those dependencies that are +currently installed.

By default, deps shows required and recommended dependencies for formulae. To include the :build type dependencies, pass --include-build. Similarly, pass --include-optional to include :optional dependencies. To skip :recommended type dependencies, pass --skip-recommended.

+
deps --tree [filters] (formulae|--installed)

Show dependencies as a tree. When given multiple formula arguments, output +individual trees for every formula.

+ +

If --installed is passed, output a tree for every installed formula.

+ +

The filters placeholder is any combination of options --include-build, +--include-optional, and --skip-recommended as documented above.

+
deps [filters] (--installed|--all)

Show dependencies for installed or all available formulae. Every line of +output starts with the formula name, followed by a colon and all direct +dependencies of that formula.

+ +

The filters placeholder is any combination of options --include-build, +--include-optional, and --skip-recommended as documented above.

desc formula

Display formula's name and one-line description.

desc [-s|-n|-d] pattern

Search both name and description (-s), just the names (-n), or just the descriptions (-d) for <pattern>. <pattern> is by default interpreted diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1 index 501f1fb24..acadd5de2 100644 --- a/share/man/man1/brew.1 +++ b/share/man/man1/brew.1 @@ -123,8 +123,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\fR [\fB\-\-1\fR] [\fB\-n\fR] [\fB\-\-union\fR] [\fB\-\-tree\fR] [\fB\-\-all\fR] [\fB\-\-installed\fR] [\fB\-\-include\-build\fR] [\fB\-\-include\-optional\fR] [\fB\-\-skip\-recommended\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\. +\fBdeps\fR [\fB\-\-1\fR] [\fB\-n\fR] [\fB\-\-union\fR] [\fB\-\-installed\fR] [\fB\-\-include\-build\fR] [\fB\-\-include\-optional\fR] [\fB\-\-skip\-recommended\fR] \fIformulae\fR +Show dependencies for \fIformulae\fR\. When given multiple formula arguments, show the intersection of dependencies for \fIformulae\fR\. . .IP If \fB\-\-1\fR is passed, only show dependencies one level down, instead of recursing\. @@ -136,16 +136,27 @@ If \fB\-n\fR is passed, show dependencies in topological order\. If \fB\-\-union\fR is passed, show the union of dependencies for \fIformulae\fR, instead of the intersection\. . .IP -If \fB\-\-tree\fR is passed, show dependencies as a tree\. +If \fB\-\-installed\fR is passed, only list those dependencies that are currently installed\. . .IP -If \fB\-\-all\fR is passed, show dependencies for all formulae\. +By default, \fBdeps\fR shows required and recommended dependencies for \fIformulae\fR\. To include the \fB:build\fR type dependencies, pass \fB\-\-include\-build\fR\. Similarly, pass \fB\-\-include\-optional\fR to include \fB:optional\fR dependencies\. To skip \fB:recommended\fR type dependencies, pass \fB\-\-skip\-recommended\fR\. +. +.TP +\fBdeps\fR \fB\-\-tree\fR [\fIfilters\fR] (\fIformulae\fR|\fB\-\-installed\fR) +Show dependencies as a tree\. When given multiple formula arguments, output individual trees for every formula\. . .IP -If \fB\-\-installed\fR is passed, show dependencies for all installed formulae\. +If \fB\-\-installed\fR is passed, output a tree for every installed formula\. . .IP -By default, \fBdeps\fR shows required and recommended dependencies for \fIformulae\fR\. To include the \fB:build\fR type dependencies, pass \fB\-\-include\-build\fR\. Similarly, pass \fB\-\-include\-optional\fR to include \fB:optional\fR dependencies\. To skip \fB:recommended\fR type dependencies, pass \fB\-\-skip\-recommended\fR\. +The \fIfilters\fR placeholder is any combination of options \fB\-\-include\-build\fR, \fB\-\-include\-optional\fR, and \fB\-\-skip\-recommended\fR as documented above\. +. +.TP +\fBdeps\fR [\fIfilters\fR] (\fB\-\-installed\fR|\fB\-\-all\fR) +Show dependencies for installed or all available formulae\. Every line of output starts with the formula name, followed by a colon and all direct dependencies of that formula\. +. +.IP +The \fIfilters\fR placeholder is any combination of options \fB\-\-include\-build\fR, \fB\-\-include\-optional\fR, and \fB\-\-skip\-recommended\fR as documented above\. . .TP \fBdesc\fR \fIformula\fR -- cgit v1.2.3