cargo-yank(1)

概要

cargo yank [选项] crate@版本
cargo yank [选项] --version 版本 [crate]

描述

yank 命令从服务器的索引中移除先前发布的 crate 版本。此命令不会删除任何数据，该 crate 仍然可以通过注册表的下载链接进行下载。

对于任何没有预先存在的 lockfile 的新项目或 checkout，Cargo 将不会使用被 yank 的版本，并且如果你的 crate 不再有任何兼容版本，则会生成错误。

此命令需要你使用 --token 选项或 cargo-login(1) 进行身份验证。

如果未指定 crate 名称，则将使用当前目录中的包名称。

例如，foo crate 发布了版本 1.5.0，而另一个 crate bar 声明了对版本 foo = "1.5" 的依赖。现在 foo 发布了一个新的、但与 semver 不兼容的版本 2.0.0，并且发现 1.5.0 存在一个严重问题。如果 1.5.0 被 yank，则任何没有现有 lockfile 的新项目或 checkout 都无法使用 crate bar，因为它依赖于 1.5。

在这种情况下，foo 的维护者应首先发布一个与 semver 兼容的版本（例如 1.5.1），然后再 yank 1.5.0，以便 bar 和所有依赖于 bar 的项目能够继续工作。

再举一个例子，考虑一个已发布版本为 1.5.0、1.5.1、1.5.2、2.0.0 和 3.0.0 的 crate bar。下表标识了在没有 lockfile 的情况下，对于不同的 SemVer 要求，在给定版本被 yank 后 cargo 可能使用的版本

被 Yank 的版本 / SemVer 要求	`bar = "1.5.0"`	`bar = "=1.5.0"`	`bar = "2.0.0"`
`1.5.0`	使用 `1.5.1` 或 `1.5.2`	返回错误	使用 `2.0.0`
`1.5.1`	使用 `1.5.0` 或 `1.5.2`	使用 `1.5.0`	使用 `2.0.0`
`2.0.0`	使用 `1.5.0`、`1.5.1` 或 `1.5.2`	使用 `1.5.0`	返回错误

何时 yank

只有在特殊情况下才应该 yank crates，例如，意外发布、无意的 SemVer 破坏或严重损坏且无法使用的 crate。在存在安全漏洞的情况下，RustSec 通常是一种更少破坏性的机制，用于通知用户并鼓励他们升级，并且避免了可能对下游造成重大破坏的可能性，无论是否存在该漏洞的易感性。

常见的流程是先发布与 semver 兼容的版本，然后再 yank crate，以降低阻止依赖 crate 编译的可能性。

在处理已发布 crate 的版权、许可或个人数据问题时，简单地 yank 它可能不足以解决问题。在这种情况下，请联系你使用的注册表的维护者。对于 crates.io，请参阅他们的策略，并通过 [email protected] 联系他们。

如果凭据已泄漏，建议立即撤销它们。一旦发布了 crate，就无法确定泄漏的凭据是否已被复制。Yank crate 只能阻止新用户下载它，但不能阻止已经下载它的人保留甚至传播泄漏的凭据。

选项

Yank 选项

--vers 版本

--version 版本

要 yank 或取消 yank 的版本。

--undo

撤消 yank，将版本放回索引中。

--token token

用于身份验证的 API token。这将覆盖存储在凭据文件（由 cargo-login(1) 创建）中的 token。

Cargo 配置环境变量可用于覆盖存储在凭据文件中的 token。crates.io 的 token 可以使用 CARGO_REGISTRY_TOKEN 环境变量指定。其他注册表的 token 可以使用 CARGO_REGISTRIES_NAME_TOKEN 格式的环境变量指定，其中 NAME 是注册表的名称，全部为大写。

--index 索引

要使用的注册表索引的 URL。

--registry 注册表

要使用的注册表的名称。注册表名称在 Cargo 配置文件中定义。如果未指定，则使用默认注册表，该注册表由 registry.default 配置键定义，默认为 crates-io。

显示选项

-v

--verbose

使用详细输出。可以指定两次以获得“非常详细”的输出，其中包括额外的输出，例如依赖项警告和构建脚本输出。也可以使用 term.verbose 配置值指定。

-q

--quiet

不打印 cargo 日志消息。也可以使用 term.quiet 配置值指定。

--color 何时

控制何时使用彩色输出。有效值

auto（默认）：自动检测终端上是否支持颜色。
always：始终显示颜色。
never：从不显示颜色。

也可以使用 term.color 配置值指定。

通用选项

+工具链

如果 Cargo 是使用 rustup 安装的，并且 cargo 的第一个参数以 + 开头，则它将被解释为 rustup 工具链名称（例如 +stable 或 +nightly）。有关工具链覆盖如何工作的更多信息，请参阅 rustup 文档。

--config KEY=VALUE 或 PATH

覆盖 Cargo 配置值。参数应采用 KEY=VALUE 的 TOML 语法，或作为指向额外配置文件的路径提供。可以多次指定此标志。有关更多信息，请参阅命令行覆盖部分。

-C PATH

在执行任何指定操作之前，更改当前工作目录。这会影响诸如 cargo 默认查找项目清单 (Cargo.toml) 的位置，以及搜索发现 .cargo/config.toml 的目录等。此选项必须出现在命令名称之前，例如 cargo -C path/to/my-project build。

此选项仅在 nightly channel 上可用，并且需要使用 -Z unstable-options 标志启用（请参阅 #10098）。

-h

--help

打印帮助信息。

-Z flag

Cargo 的不稳定（仅限 nightly）标志。运行 cargo -Z help 以了解详细信息。

环境变量

有关 Cargo 读取的环境变量的详细信息，请参阅参考资料。

退出状态

0：Cargo 成功完成。
101：Cargo 未能完成。

示例

从索引中 yank 一个 crate
```
cargo yank [email protected]
```

另请参阅

cargo(1), cargo-login(1), cargo-publish(1)

Cargo 书