Switch --invert to take the package name as an argument.

Author: ehuss

src/bin/cargo/commands/tree.rs

@@ -2,6 +2,7 @@ use crate::command_prelude::*;
 use anyhow::{bail, format_err};
 use cargo::core::dependency::DepKind;
 use cargo::ops::tree::{self, EdgeKind};
+use cargo::ops::Packages;
 use cargo::util::CargoResult;
 use std::collections::HashSet;
 use std::str::FromStr;
@@ -40,7 +41,14 @@ pub fn cli() -> App {
             )
             .short("e"),
         )
-        .arg(opt("invert", "Invert the tree direction").short("i"))
+        .arg(
+            optional_multi_opt(
+                "invert",
+                "SPEC",
+                "Invert the tree direction and focus on the given package",
+            )
+            .short("i"),
+        )
         .arg(Arg::with_name("no-indent").long("no-indent").hidden(true))
         .arg(
             Arg::with_name("prefix-depth")
@@ -119,17 +127,48 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
     let edge_kinds = parse_edge_kinds(config, args)?;
     let graph_features = edge_kinds.contains(&EdgeKind::Feature);
 
+    let packages = args.packages_from_flags()?;
+    let mut invert = args
+        .values_of("invert")
+        .map_or_else(|| Vec::new(), |is| is.map(|s| s.to_string()).collect());
+    if args.is_present_with_zero_values("invert") {
+        match &packages {
+            Packages::Packages(ps) => {
+                // Backwards compatibility with old syntax of `cargo tree -i -p foo`.
+                invert.extend(ps.clone());
+            }
+            _ => {
+                return Err(format_err!(
+                    "The `-i` flag requires a package name.\n\
+\n\
+The `-i` flag is used to inspect the reverse dependencies of a specific\n\
+package. It will invert the tree and display the packages that depend on the\n\
+given package.\n\
+\n\
+Note that in a workspace, by default it will only display the package's\n\
+reverse dependencies inside the tree of the workspace member in the current\n\
+directory. The --workspace flag can be used to extend it so that it will show\n\
+the package's reverse dependencies across the entire workspace. The -p flag\n\
+can be used to display the package's reverse dependencies only with the\n\
+subtree of the package given to -p.\n\
+"
+                )
+                .into());
+            }
+        }
+    }
+
     let ws = args.workspace(config)?;
     let charset = tree::Charset::from_str(args.value_of("charset").unwrap())
         .map_err(|e| anyhow::anyhow!("{}", e))?;
     let opts = tree::TreeOptions {
         features: values(args, "features"),
         all_features: args.is_present("all-features"),
         no_default_features: args.is_present("no-default-features"),
-        packages: args.packages_from_flags()?,
+        packages,
         target,
         edge_kinds,
-        invert: args.is_present("invert"),
+        invert,
         prefix,
         no_dedupe: args.is_present("no-dedupe"),
         duplicates: args.is_present("duplicates"),

src/cargo/ops/tree/mod.rs

@@ -4,7 +4,7 @@ use self::format::Pattern;
 use crate::core::compiler::{CompileKind, RustcTargetData};
 use crate::core::dependency::DepKind;
 use crate::core::resolver::{HasDevUnits, ResolveOpts};
-use crate::core::{Package, PackageId, Workspace};
+use crate::core::{Package, PackageId, PackageIdSpec, Workspace};
 use crate::ops::{self, Packages};
 use crate::util::CargoResult;
 use anyhow::{bail, Context};
@@ -27,7 +27,7 @@ pub struct TreeOptions {
     pub target: Target,
     /// The dependency kinds to display.
     pub edge_kinds: HashSet<EdgeKind>,
-    pub invert: bool,
+    pub invert: Vec<String>,
     /// The style of prefix for each line.
     pub prefix: Prefix,
     /// If `true`, duplicates will be repeated.
@@ -177,7 +177,15 @@ pub fn build_and_print(ws: &Workspace<'_>, opts: &TreeOptions) -> CargoResult<()
         opts,
     )?;
 
-    let root_ids = ws_resolve.targeted_resolve.specs_to_ids(&specs)?;
+    let root_specs = if opts.invert.is_empty() {
+        specs
+    } else {
+        opts.invert
+            .iter()
+            .map(|p| PackageIdSpec::parse(p))
+            .collect::<CargoResult<Vec<PackageIdSpec>>>()?
+    };
+    let root_ids = ws_resolve.targeted_resolve.specs_to_ids(&root_specs)?;
     let root_indexes = graph.indexes_from_ids(&root_ids);
 
     let root_indexes = if opts.duplicates {
@@ -188,7 +196,7 @@ pub fn build_and_print(ws: &Workspace<'_>, opts: &TreeOptions) -> CargoResult<()
         root_indexes
     };
 
-    if opts.invert || opts.duplicates {
+    if !opts.invert.is_empty() || opts.duplicates {
         graph.invert();
     }
 

src/doc/asciidoc-extension.rb

@@ -84,6 +84,20 @@ def process document, output
   end
 end
 
+# Man pages are ASCII only. Unfortunately asciidoc doesn't process these
+# characters for us. The `cargo tree` manpage needs a little assistance.
+class SpecialCharPostprocessor < Extensions::Postprocessor
+  def process document, output
+    if document.basebackend? 'manpage'
+      output = output.gsub(/│/, '|')
+        .gsub(/├/, '|')
+        .gsub(/└/, '`')
+        .gsub(/─/, '\-')
+    end
+    output
+  end
+end
+
 # General utility for converting text. Example:
 #
 #   convert:lowercase[{somevar}]
@@ -107,4 +121,5 @@ def process parent, target, attrs
   inline_macro LinkCargoInlineMacro
   inline_macro ConvertInlineMacro
   postprocessor MonoPostprocessor
+  postprocessor SpecialCharPostprocessor
 end

src/doc/man/cargo-tree.adoc

@@ -52,17 +52,24 @@ myproject v0.1.0 (/myproject)
 
 In this tree, `myproject` depends on `log` with the `serde` feature. `log` in
 turn depends on `cfg-if` with "default" features. When using `-e features` it
-can be helpful to use `-i` and `-p` flags to show how the features flow into a
-package. See the examples below for more detail.
+can be helpful to use `-i` flag to show how the features flow into a package.
+See the examples below for more detail.
 
 == OPTIONS
 
 === Tree Options
 
-*-i*::
-*--invert*::
-    Invert the tree. Typically this flag is used with the `-p` flag to show
-    the dependencies for a specific package.
+*-i* _SPEC_::
+*--invert* _SPEC_::
+    Show the reverse dependencies for the given package. This flag will invert
+    the tree and display the packages that depend on the given package.
++
+Note that in a workspace, by default it will only display the package's
+reverse dependencies inside the tree of the workspace member in the current
+directory. The `--workspace` flag can be used to extend it so that it will
+show the package's reverse dependencies across the entire workspace. The `-p`
+flag can be used to display the package's reverse dependencies only with the
+subtree of the package given to `-p`.
 
 *--no-dedupe*::
     Do not de-duplicate repeated dependencies. Usually, when a package has
@@ -161,9 +168,9 @@ include::section-exit-status.adoc[]
 
     cargo tree
 
-. Display all the packages that depend on the specified package:
+. Display all the packages that depend on the `syn` package:
 
-    cargo tree -i -p syn
+    cargo tree -i syn
 
 . Show the features enabled on each package:
 
@@ -174,13 +181,13 @@ include::section-exit-status.adoc[]
 
     cargo tree -d
 
-. Explain why features are enabled for the given package:
+. Explain why features are enabled for the `syn` package:
 
-    cargo tree -e features -i -p syn
+    cargo tree -e features -i syn
 +
 The `-e features` flag is used to show features. The `-i` flag is used to
-invert the graph so that it displays the packages that depend on `syn` (not
-what `syn` depends on). An example of what this would display:
+invert the graph so that it displays the packages that depend on `syn`. An
+example of what this would display:
 +
 ----
 syn v1.0.17

src/doc/man/generated/cargo-tree.html

@@ -57,8 +57,8 @@ <h2 id="cargo_tree_description">DESCRIPTION</h2>
 <div class="paragraph">
 <p>In this tree, <code>myproject</code> depends on <code>log</code> with the <code>serde</code> feature. <code>log</code> in
 turn depends on <code>cfg-if</code> with "default" features. When using <code>-e features</code> it
-can be helpful to use <code>-i</code> and <code>-p</code> flags to show how the features flow into a
-package. See the examples below for more detail.</p>
+can be helpful to use <code>-i</code> flag to show how the features flow into a package.
+See the examples below for more detail.</p>
 </div>
 </div>
 </div>
@@ -69,11 +69,19 @@ <h2 id="cargo_tree_options">OPTIONS</h2>
 <h3 id="cargo_tree_tree_options">Tree Options</h3>
 <div class="dlist">
 <dl>
-<dt class="hdlist1"><strong>-i</strong></dt>
-<dt class="hdlist1"><strong>--invert</strong></dt>
+<dt class="hdlist1"><strong>-i</strong> <em>SPEC</em></dt>
+<dt class="hdlist1"><strong>--invert</strong> <em>SPEC</em></dt>
 <dd>
-<p>Invert the tree. Typically this flag is used with the <code>-p</code> flag to show
-the dependencies for a specific package.</p>
+<p>Show the reverse dependencies for the given package. This flag will invert
+the tree and display the packages that depend on the given package.</p>
+<div class="paragraph">
+<p>Note that in a workspace, by default it will only display the package&#8217;s
+reverse dependencies inside the tree of the workspace member in the current
+directory. The <code>--workspace</code> flag can be used to extend it so that it will
+show the package&#8217;s reverse dependencies across the entire workspace. The <code>-p</code>
+flag can be used to display the package&#8217;s reverse dependencies only with the
+subtree of the package given to <code>-p</code>.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--no-dedupe</strong></dt>
 <dd>
@@ -412,10 +420,10 @@ <h2 id="cargo_tree_examples">EXAMPLES</h2>
 </div>
 </li>
 <li>
-<p>Display all the packages that depend on the specified package:</p>
+<p>Display all the packages that depend on the <code>syn</code> package:</p>
 <div class="literalblock">
 <div class="content">
-<pre>cargo tree -i -p syn</pre>
+<pre>cargo tree -i syn</pre>
 </div>
 </div>
 </li>
@@ -437,16 +445,16 @@ <h2 id="cargo_tree_examples">EXAMPLES</h2>
 </div>
 </li>
 <li>
-<p>Explain why features are enabled for the given package:</p>
+<p>Explain why features are enabled for the <code>syn</code> package:</p>
 <div class="literalblock">
 <div class="content">
-<pre>cargo tree -e features -i -p syn</pre>
+<pre>cargo tree -e features -i syn</pre>
 </div>
 </div>
 <div class="paragraph">
 <p>The <code>-e features</code> flag is used to show features. The <code>-i</code> flag is used to
-invert the graph so that it displays the packages that depend on <code>syn</code> (not
-what <code>syn</code> depends on). An example of what this would display:</p>
+invert the graph so that it displays the packages that depend on <code>syn</code>. An
+example of what this would display:</p>
 </div>
 <div class="listingblock">
 <div class="content">