Auto merge of #14739 - weihanglo:cmd, r=epage

fix: clean up for deprecated and removed commands

### What does this PR try to resolve?

This PR is a follow-up of <#14679>.

* A new doc page for deprecated and removed commands
* Remove shell completions for deprecated commands
* Remove `verify-project` and `read-manifest` from `cargo --list` output.

### How should we test and review this PR?

`mdbook serve src/doc` and read the doc.

I've set up redirections for all removed/deprecated commands to maintain consistency,
though only `verify-project` really need it I believe.

src/bin/cargo/commands/git_checkout.rs

@@ -1,10 +1,12 @@
+//! Removed.
+
 use crate::command_prelude::*;
 
 const REMOVED: &str = "The `git-checkout` command has been removed.";
 
 pub fn cli() -> Command {
     subcommand("git-checkout")
-        .about("This command has been removed")
+        .about("REMOVED: This command has been removed")
         .hide(true)
         .override_help(REMOVED)
 }

src/bin/cargo/commands/read_manifest.rs

@@ -1,12 +1,15 @@
+//! Deprecated.
+
 use crate::command_prelude::*;
 
 pub fn cli() -> Command {
     subcommand("read-manifest")
+        .hide(true)
         .about(color_print::cstr!(
             "\
-Print a JSON representation of a Cargo.toml manifest.
+DEPRECATED: Print a JSON representation of a Cargo.toml manifest.
 
-Deprecated, use `<cyan,bold>cargo metadata --no-deps</>` instead.\
+Use `<cyan,bold>cargo metadata --no-deps</>` instead.\
 "
         ))
         .arg_silent_suggestion()

src/bin/cargo/commands/verify_project.rs

@@ -1,15 +1,18 @@
+//! Deprecated.
+
 use crate::command_prelude::*;
 
 use std::collections::HashMap;
 use std::process;
 
 pub fn cli() -> Command {
     subcommand("verify-project")
+        .hide(true)
         .about(
             "\
-Check correctness of crate manifest.
+DEPRECATED: Check correctness of crate manifest.
 
-Deprecated, see https://github.com/rust-lang/cargo/issues/14679.",
+See https://github.com/rust-lang/cargo/issues/14679.",
         )
         .arg_silent_suggestion()
         .arg_manifest_path()

src/doc/book.toml

@@ -10,3 +10,6 @@ search.use-boolean-and = true
 
 [output.html.redirect]
 "/guide/build-cache.html" = "../reference/build-cache.html"
+"/commands/cargo-git-checkout.html" = "./deprecated-and-removed.html"
+"/commands/cargo-read-manifest.html" = "./deprecated-and-removed.html"
+"/commands/cargo-verify-project.html" = "./deprecated-and-removed.html"

src/doc/src/SUMMARY.md

@@ -94,6 +94,7 @@
         * [cargo package](commands/cargo-package.md)
         * [cargo publish](commands/cargo-publish.md)
         * [cargo yank](commands/cargo-yank.md)
+    * [Deprecated and Removed](commands/deprecated-and-removed.md)
 
 * [FAQ](faq.md)
 * [Appendix: Glossary](appendix/glossary.md)

src/doc/src/commands/deprecated-and-removed.md

@@ -0,0 +1,10 @@
+## Deprecated and Removed Commands
+
+These commands have been deprecated or removed in early Rust releases.
+Deprecated commands receive only critical bug fixes,
+and may be removed in future versions.
+Removed commands are no longer functional and are unsupported.
+
+* `read-manifest` --- deprecated since Rust 1.13
+* `git-checkout` --- removed since Rust 1.44
+* `verify-project` --- deprecated since Rust 1.84

src/doc/src/commands/index.md

@@ -4,3 +4,4 @@
 * [Manifest Commands](manifest-commands.md)
 * [Package Commands](package-commands.md)
 * [Publishing Commands](publishing-commands.md)
+* [Deprecated and Removed](deprecated-and-removed.md)

src/etc/_cargo

@@ -254,10 +254,6 @@ _cargo() {
                         '--dry-run[perform all checks without uploading]'
                         ;;
 
-                read-manifest)
-                    _arguments -s -S $common $manifest
-                        ;;
-
                 remove | rm)
                     _arguments -s -A "^--" $common $manifest \
                         "--dev[remove as a dev dependency]" \
@@ -356,10 +352,6 @@ _cargo() {
                         '*:package:_cargo_package_names'
                         ;;
 
-                verify-project)
-                    _arguments -s -S $common $manifest
-                        ;;
-
                 version)
                     _arguments -s -S $common
                         ;;

src/etc/cargo.bashcomp.sh

@@ -74,7 +74,6 @@ _cargo()
 	local opt__package="$opt_common $opt_mani $opt_feat $opt_lock $opt_parallel --allow-dirty -l --list --no-verify --no-metadata --index --registry --target --target-dir"
 	local opt__pkgid="$opt_common $opt_mani $opt_lock $opt_pkg"
 	local opt__publish="$opt_common $opt_mani $opt_feat $opt_lock $opt_parallel --allow-dirty --dry-run --token --no-verify --index --registry --target --target-dir"
-	local opt__read_manifest="$opt_help $opt_quiet $opt_verbose $opt_mani $opt_color $opt_lock --no-deps"
 	local opt__remove="$opt_common $opt_pkg $opt_lock $opt_mani --dry-run --dev --build --target"
 	local opt__rm="$opt__remove"
 	local opt__report="$opt_help $opt_verbose $opt_color future-incompat future-incompatibilities"
@@ -90,7 +89,6 @@ _cargo()
 	local opt__uninstall="$opt_common $opt_lock $opt_pkg --bin --root"
 	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"
 	local opt__yank="$opt_common $opt_lock --version --undo --index --token --registry"
 	local opt__libtest="--help --include-ignored --ignored --test --bench --list --logfile --nocapture --test-threads --skip -q --quiet --exact --color --format"

tests/testsuite/cargo_command.rs

@@ -36,7 +36,7 @@ fn list_commands_with_descriptions() {
 ...
     r                    alias: run
 ...
-    read-manifest        Print a JSON representation of a Cargo.toml manifest.
+    read-manifest        DEPRECATED: Print a JSON representation of a Cargo.toml manifest.
 ...
     t                    alias: test
 ...