fix(update): Clarify meaning of --aggressive as --recursive

When working on cargo-upgrade, I found the meaning of `--aggressive`
confusing and named it `--recursive` there.

Renaming this in `cargo update` (with a backwards compatible alias) was
referenced in #12425.

Author: epage

src/bin/cargo/commands/update.rs

@@ -24,9 +24,10 @@ pub fn cli() -> Command {
         .arg_dry_run("Don't actually write the lockfile")
         .arg(
             flag(
-                "aggressive",
+                "recursive",
                 "Force updating all dependencies of [SPEC]... as well",
             )
+            .alias("aggressive")
             .conflicts_with("precise"),
         )
         .arg(
@@ -68,7 +69,7 @@ pub fn exec(config: &mut Config, args: &ArgMatches) -> CliResult {
     }
 
     let update_opts = UpdateOptions {
-        aggressive: args.flag("aggressive"),
+        recursive: args.flag("recursive"),
         precise: args.get_one::<String>("precise").map(String::as_str),
         to_update,
         dry_run: args.dry_run(),

src/cargo/ops/cargo_generate_lockfile.rs

@@ -14,7 +14,7 @@ pub struct UpdateOptions<'a> {
     pub config: &'a Config,
     pub to_update: Vec<String>,
     pub precise: Option<&'a str>,
-    pub aggressive: bool,
+    pub recursive: bool,
     pub dry_run: bool,
     pub workspace: bool,
 }
@@ -38,8 +38,8 @@ pub fn generate_lockfile(ws: &Workspace<'_>) -> CargoResult<()> {
 }
 
 pub fn update_lockfile(ws: &Workspace<'_>, opts: &UpdateOptions<'_>) -> CargoResult<()> {
-    if opts.aggressive && opts.precise.is_some() {
-        anyhow::bail!("cannot specify both aggressive and precise simultaneously")
+    if opts.recursive && opts.precise.is_some() {
+        anyhow::bail!("cannot specify both recursive and precise simultaneously")
     }
 
     if ws.members().count() == 0 {
@@ -89,7 +89,7 @@ pub fn update_lockfile(ws: &Workspace<'_>, opts: &UpdateOptions<'_>) -> CargoRes
         let mut sources = Vec::new();
         for name in opts.to_update.iter() {
             let dep = previous_resolve.query(name)?;
-            if opts.aggressive {
+            if opts.recursive {
                 fill_with_deps(&previous_resolve, dep, &mut to_avoid, &mut HashSet::new());
             } else {
                 to_avoid.insert(dep);

src/doc/man/cargo-update.md

@@ -33,7 +33,7 @@ will remain locked at their currently recorded versions.
 If _spec_ is not specified, all dependencies are updated.
 {{/option}}
 
-{{#option "`--aggressive`" }}
+{{#option "`--recursive`" }}
 When used with _spec_, dependencies of _spec_ are forced to update as well.
 Cannot be used with `--precise`.
 {{/option}}

src/doc/man/generated_txt/cargo-update.txt

@@ -26,7 +26,7 @@ OPTIONS
 
            If spec is not specified, all dependencies are updated.
 
-       --aggressive
+       --recursive
            When used with spec, dependencies of spec are forced to update as
            well. Cannot be used with --precise.
 

src/doc/src/commands/cargo-update.md

@@ -31,7 +31,7 @@ will remain locked at their currently recorded versions.</p>
 <p>If <em>spec</em> is not specified, all dependencies are updated.</dd>
 
 
-<dt class="option-term" id="option-cargo-update---aggressive"><a class="option-anchor" href="#option-cargo-update---aggressive"></a><code>--aggressive</code></dt>
+<dt class="option-term" id="option-cargo-update---recursive"><a class="option-anchor" href="#option-cargo-update---recursive"></a><code>--recursive</code></dt>
 <dd class="option-desc">When used with <em>spec</em>, dependencies of <em>spec</em> are forced to update as well.
 Cannot be used with <code>--precise</code>.</dd>
 

src/doc/src/reference/resolver.md

@@ -342,7 +342,7 @@ instead.
 [`cargo update`] can be used to update the entries in `Cargo.lock` when new
 versions are published. Without any options, it will attempt to update all
 packages in the lock file. The `-p` flag can be used to target the update for
-a specific package, and other flags such as `--aggressive` or `--precise` can
+a specific package, and other flags such as `--recursive` or `--precise` can
 be used to control how versions are selected.
 
 [`cargo build`]: ../commands/cargo-build.md

src/etc/_cargo

@@ -342,6 +342,7 @@ _cargo() {
                 update)
                     _arguments -s -S $common $manifest \
                         '--aggressive=[force dependency update]' \
+                        '--recursive=[force dependency update]' \
                         "--dry-run[don't actually write the lockfile]" \
                         '(-p --package)'{-p+,--package=}'[specify package to update]:package:_cargo_package_names' \
                         '--precise=[update single dependency to precise release]:release' \

src/etc/cargo.bashcomp.sh

@@ -87,7 +87,7 @@ _cargo()
 	local opt__t="$opt__test"
 	local opt__tree="$opt_common $opt_pkg_spec $opt_feat $opt_mani $opt_lock --target -i --invert --prefix --no-dedupe --duplicates -d --charset -f --format -e --edges"
 	local opt__uninstall="$opt_common $opt_lock $opt_pkg --bin --root"
-	local opt__update="$opt_common $opt_mani $opt_lock $opt_pkg --aggressive --precise --dry-run"
+	local opt__update="$opt_common $opt_mani $opt_lock $opt_pkg --aggressive --recursive --precise --dry-run"
 	local opt__vendor="$opt_common $opt_mani $opt_lock $opt_sync --no-delete --respect-source-config --versioned-dirs"
 	local opt__verify_project="$opt_common $opt_mani $opt_lock"
 	local opt__version="$opt_common $opt_lock"

src/etc/man/cargo-update.1

@@ -28,7 +28,7 @@ will remain locked at their currently recorded versions.
 If \fIspec\fR is not specified, all dependencies are updated.
 .RE
 .sp
-\fB\-\-aggressive\fR
+\fB\-\-recursive\fR
 .RS 4
 When used with \fIspec\fR, dependencies of \fIspec\fR are forced to update as well.
 Cannot be used with \fB\-\-precise\fR\&.

tests/testsuite/cargo_update/help/stdout.log

@@ -4,7 +4,7 @@ Usage: cargo[EXE] update [OPTIONS] [SPEC]...
 
 Options:
       --dry-run             Don't actually write the lockfile
-      --aggressive          Force updating all dependencies of [SPEC]... as well
+      --recursive           Force updating all dependencies of [SPEC]... as well
       --precise <PRECISE>   Update [SPEC] to exactly PRECISE
   -q, --quiet               Do not print cargo log messages
   -v, --verbose...          Use verbose output (-vv very verbose/build.rs output)

tests/testsuite/git.rs

@@ -769,9 +769,9 @@ Caused by:
         .with_stdout("")
         .run();
 
-    // Updating aggressively should, however, update the repo.
-    println!("dep1 aggressive update");
-    p.cargo("update dep1 --aggressive")
+    // Updating recursively should, however, update the repo.
+    println!("dep1 recursive update");
+    p.cargo("update dep1 --recursive")
         .with_stderr(&format!(
             "[UPDATING] git repository `{}`\n\
              [UPDATING] bar v0.5.0 ([..]) -> #[..]\n\

tests/testsuite/update.rs

@@ -428,7 +428,44 @@ fn update_precise_do_not_force_update_deps() {
 }
 
 #[cargo_test]
-fn update_aggressive() {
+fn update_recursive() {
+    Package::new("log", "0.1.0").publish();
+    Package::new("serde", "0.2.1").dep("log", "0.1").publish();
+
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+                [package]
+                name = "bar"
+                version = "0.0.1"
+                authors = []
+
+                [dependencies]
+                serde = "0.2"
+            "#,
+        )
+        .file("src/lib.rs", "")
+        .build();
+
+    p.cargo("check").run();
+
+    Package::new("log", "0.1.1").publish();
+    Package::new("serde", "0.2.2").dep("log", "0.1").publish();
+
+    p.cargo("update serde:0.2.1 --recursive")
+        .with_stderr(
+            "\
+[UPDATING] `[..]` index
+[UPDATING] log v0.1.0 -> v0.1.1
+[UPDATING] serde v0.2.1 -> v0.2.2
+",
+        )
+        .run();
+}
+
+#[cargo_test]
+fn update_aggressive_alias_for_recursive() {
     Package::new("log", "0.1.0").publish();
     Package::new("serde", "0.2.1").dep("log", "0.1").publish();
 
@@ -465,7 +502,7 @@ fn update_aggressive() {
 }
 
 #[cargo_test]
-fn update_aggressive_conflicts_with_precise() {
+fn update_recursive_conflicts_with_precise() {
     Package::new("log", "0.1.0").publish();
     Package::new("serde", "0.2.1").dep("log", "0.1").publish();
 
@@ -490,11 +527,11 @@ fn update_aggressive_conflicts_with_precise() {
     Package::new("log", "0.1.1").publish();
     Package::new("serde", "0.2.2").dep("log", "0.1").publish();
 
-    p.cargo("update serde:0.2.1 --precise 0.2.2 --aggressive")
+    p.cargo("update serde:0.2.1 --precise 0.2.2 --recursive")
         .with_status(1)
         .with_stderr(
             "\
-error: the argument '--precise <PRECISE>' cannot be used with '--aggressive'
+error: the argument '--precise <PRECISE>' cannot be used with '--recursive'
 
 Usage: cargo[EXE] update --precise <PRECISE> <SPEC|--package [<SPEC>]>