Auto merge of #6801 - ehuss:install-flags, r=Eh2406

cargo install: Be more restrictive about cli flags. Several flags in `cargo install` are silently ignored depending on what is used. This adds some validation so that invalid combinations are rejected. I have been sorta confused by these in the past. - The 3 source flags (`--git`, `--path`, and `--registry`) are mutually exclusive. - The `--git` flags (branch, tag, rev) are only valid if `--git` is specified. - `--registry` requires a crate name (otherwise it would be ignored and treated as a path source). - `--version` is only used when a crate name is specified.
rust-lang · Apr 1, 2019 · fccca68 · fccca68
2 parents 8cf0c95 + b666a9f
commit fccca68
Show file tree

Hide file tree

Showing 5 changed files with 60 additions and 34 deletions.
diff --git a/src/bin/cargo/commands/install.rs b/src/bin/cargo/commands/install.rs
@@ -10,15 +10,36 @@ pub fn cli() -> App {
         .arg(opt("quiet", "No output printed to stdout").short("q"))
         .arg(Arg::with_name("crate").empty_values(false).multiple(true))
         .arg(
-            opt("version", "Specify a version to install from crates.io")
+            opt("version", "Specify a version to install")
                 .alias("vers")
-                .value_name("VERSION"),
+                .value_name("VERSION")
+                .requires("crate"),
+        )
+        .arg(
+            opt("git", "Git URL to install the specified crate from")
+                .value_name("URL")
+                .conflicts_with_all(&["path", "registry"]),
+        )
+        .arg(
+            opt("branch", "Branch to use when installing from git")
+                .value_name("BRANCH")
+                .requires("git"),
+        )
+        .arg(
+            opt("tag", "Tag to use when installing from git")
+                .value_name("TAG")
+                .requires("git"),
+        )
+        .arg(
+            opt("rev", "Specific commit to use when installing from git")
+                .value_name("SHA")
+                .requires("git"),
+        )
+        .arg(
+            opt("path", "Filesystem path to local crate to install")
+                .value_name("PATH")
+                .conflicts_with_all(&["git", "registry"]),
         )
-        .arg(opt("git", "Git URL to install the specified crate from").value_name("URL"))
-        .arg(opt("branch", "Branch to use when installing from git").value_name("BRANCH"))
-        .arg(opt("tag", "Tag to use when installing from git").value_name("TAG"))
-        .arg(opt("rev", "Specific commit to use when installing from git").value_name("SHA"))
-        .arg(opt("path", "Filesystem path to local crate to install").value_name("PATH"))
         .arg(opt(
             "list",
             "list all installed packages and their versions",
@@ -35,7 +56,12 @@ pub fn cli() -> App {
         )
         .arg_target_triple("Build for the target triple")
         .arg(opt("root", "Directory to install packages into").value_name("DIR"))
-        .arg(opt("registry", "Registry to use").value_name("REGISTRY"))
+        .arg(
+            opt("registry", "Registry to use")
+                .value_name("REGISTRY")
+                .requires("crate")
+                .conflicts_with_all(&["git", "path"]),
+        )
         .after_help(
             "\
 This command manages Cargo's local set of installed binary crates. Only packages
@@ -46,10 +72,10 @@ configuration key, and finally the home directory (which is either
 `$CARGO_HOME` if set or `$HOME/.cargo` by default).
 
 There are multiple sources from which a crate can be installed. The default
-location is crates.io but the `--git` and `--path` flags can change this source.
-If the source contains more than one package (such as crates.io or a git
-repository with multiple crates) the `<crate>` argument is required to indicate
-which crate should be installed.
+location is crates.io but the `--git`, `--path`, and `registry` flags can
+change this source. If the source contains more than one package (such as
+crates.io or a git repository with multiple crates) the `<crate>` argument is
+required to indicate which crate should be installed.
 
 Crates from crates.io can optionally specify the version they wish to install
 via the `--version` flags, and similarly packages from git repositories can
@@ -62,10 +88,10 @@ By default cargo will refuse to overwrite existing binaries. The `--force` flag
 enables overwriting existing binaries. Thus you can reinstall a crate with
 `cargo install --force <crate>`.
 
-Omitting the <crate> specification entirely will
-install the crate in the current directory. That is, `install` is equivalent to
-the more explicit `install --path .`. This behaviour is deprecated, and no
-longer supported as of the Rust 2018 edition.
+Omitting the <crate> specification entirely will install the crate in the
+current directory. That is, `install` is equivalent to the more explicit
+`install --path .`. This behaviour is deprecated, and no longer supported as
+of the Rust 2018 edition.
 
 If the source is crates.io or `--git` then by default the crate will be built
 in a temporary target directory. To avoid this, the target directory can be

diff --git a/src/doc/man/cargo-install.adoc b/src/doc/man/cargo-install.adoc
@@ -24,10 +24,10 @@ the installation root's `bin` folder.
 include::description-install-root.adoc[]
 
 There are multiple sources from which a crate can be installed. The default
-location is crates.io but the `--git` and `--path` flags can change this
-source. If the source contains more than one package (such as crates.io or a
-git repository with multiple crates) the _CRATE_ argument is required to
-indicate which crate should be installed.
+location is crates.io but the `--git`, `--path`, and `registry` flags can
+change this source. If the source contains more than one package (such as
+crates.io or a git repository with multiple crates) the _CRATE_ argument is
+required to indicate which crate should be installed.
 
 Crates from crates.io can optionally specify the version they wish to install
 via the `--version` flags, and similarly packages from git repositories can
@@ -48,7 +48,7 @@ continuous integration systems.
 
 *--vers* _VERSION_::
 *--version* _VERSION_::
-    Specify a version to install from crates.io.
+    Specify a version to install.
 
 *--git* _URL_::
     Git URL to install the specified crate from.

diff --git a/src/doc/man/generated/cargo-install.html b/src/doc/man/generated/cargo-install.html
@@ -45,10 +45,10 @@ <h2 id="cargo_install_description">DESCRIPTION</h2>
 </div>
 <div class="paragraph">
 <p>There are multiple sources from which a crate can be installed. The default
-location is crates.io but the <code>--git</code> and <code>--path</code> flags can change this
-source. If the source contains more than one package (such as crates.io or a
-git repository with multiple crates) the <em>CRATE</em> argument is required to
-indicate which crate should be installed.</p>
+location is crates.io but the <code>--git</code>, <code>--path</code>, and <code>registry</code> flags can
+change this source. If the source contains more than one package (such as
+crates.io or a git repository with multiple crates) the <em>CRATE</em> argument is
+required to indicate which crate should be installed.</p>
 </div>
 <div class="paragraph">
 <p>Crates from crates.io can optionally specify the version they wish to install
@@ -77,7 +77,7 @@ <h3 id="cargo_install_install_options">Install Options</h3>
 <dt class="hdlist1"><strong>--vers</strong> <em>VERSION</em></dt>
 <dt class="hdlist1"><strong>--version</strong> <em>VERSION</em></dt>
 <dd>
-<p>Specify a version to install from crates.io.</p>
+<p>Specify a version to install.</p>
 </dd>
 <dt class="hdlist1"><strong>--git</strong> <em>URL</em></dt>
 <dd>

diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1
@@ -2,12 +2,12 @@
 .\"     Title: cargo-install
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 1.5.8
-.\"      Date: 2019-01-23
+.\"      Date: 2019-03-31
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-INSTALL" "1" "2019-01-23" "\ \&" "\ \&"
+.TH "CARGO\-INSTALL" "1" "2019-03-31" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -103,10 +103,10 @@ The installation root is determined, in order of precedence:
 .RE
 .sp
 There are multiple sources from which a crate can be installed. The default
-location is crates.io but the \fB\-\-git\fP and \fB\-\-path\fP flags can change this
-source. If the source contains more than one package (such as crates.io or a
-git repository with multiple crates) the \fICRATE\fP argument is required to
-indicate which crate should be installed.
+location is crates.io but the \fB\-\-git\fP, \fB\-\-path\fP, and \fBregistry\fP flags can
+change this source. If the source contains more than one package (such as
+crates.io or a git repository with multiple crates) the \fICRATE\fP argument is
+required to indicate which crate should be installed.
 .sp
 Crates from crates.io can optionally specify the version they wish to install
 via the \fB\-\-version\fP flags, and similarly packages from git repositories can
@@ -125,7 +125,7 @@ continuous integration systems.
 .sp
 \fB\-\-vers\fP \fIVERSION\fP, \fB\-\-version\fP \fIVERSION\fP
 .RS 4
-Specify a version to install from crates.io.
+Specify a version to install.
 .RE
 .sp
 \fB\-\-git\fP \fIURL\fP

diff --git a/tests/testsuite/alt_registry.rs b/tests/testsuite/alt_registry.rs
@@ -620,7 +620,7 @@ Caused by:
         .run();
 
     for cmd in &[
-        "init", "install", "login", "owner", "publish", "search", "yank",
+        "init", "install foo", "login", "owner", "publish", "search", "yank",
     ] {
         p.cargo(cmd)
             .arg("--registry")