cargo-yank(1)
名称
cargo-yank - 从索引中移除已发布的包
概要
cargo yank
[选项] 包@版本
cargo yank
[选项] --version
版本 [包]
描述
yank 命令从服务器索引中移除先前发布的包版本。此命令不会删除任何数据,并且该包仍可通过注册源的下载链接下载。
对于任何没有预先存在的锁定文件的新项目或检出,Cargo 都不会使用被撤销的版本,并且如果您的包不再有任何兼容版本,则会生成错误。
此命令要求您使用 --token
选项或使用 cargo-login(1) 进行身份验证。
如果未指定包名称,它将使用当前目录中的包名称。
yank 如何工作
例如,foo
包发布了版本 1.5.0
,另一个包 bar
声明了对版本 foo = "1.5"
的依赖。现在 foo
发布了一个新的、但不兼容 semver 的版本 2.0.0
,并在 1.5.0
中发现了一个严重问题。如果 1.5.0
被撤销,则任何没有现有锁定文件的新项目或检出都将无法使用包 bar
,因为它依赖于 1.5
。
在这种情况下,foo
的维护者应首先发布一个语义化版本兼容的版本,例如 1.5.1
,然后再撤销 1.5.0
,以便 bar
和所有依赖于 bar
的项目都能继续工作。
再举一个例子,考虑一个包 bar
,它发布了版本 1.5.0
、1.5.1
、1.5.2
、2.0.0
和 3.0.0
。下表列出了在撤销给定版本后,在没有锁定文件的情况下,cargo 可以为不同的 SemVer 要求使用的版本
撤销的版本 / 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 | 返回错误 |
何时撤销
只有在特殊情况下才应撤销包,例如意外发布、无意的 SemVer 破坏或严重损坏且无法使用的包。在出现安全漏洞的情况下,RustSec 通常是一种干扰较小的机制,可以通知用户并鼓励他们升级,并避免了无论是否容易受到所讨论的漏洞的影响而导致严重下游中断的可能性。
一个常见的工作流程是在已经发布了语义化版本兼容的版本后撤销一个包,以减少阻止依赖包编译的可能性。
在处理已发布包的版权、许可或个人数据问题时,仅仅撤销它可能还不够。在这种情况下,请联系您使用的注册源的维护者。对于 crates.io,请参阅其 政策 并通过 [email protected] 与他们联系。
如果凭证泄露,建议的处理方法是立即撤销它们。一旦包被发布,就无法确定泄露的凭证是否已被复制。撤销包只会阻止新用户下载它,但无法阻止已经下载它的用户保留甚至传播泄露的凭证。
选项
Yank 选项
--vers
版本--version
版本- 要撤销或取消撤销的版本。
--undo
- 撤销撤销操作,将版本放回索引中。
--token
令牌- 身份验证时使用的 API 令牌。这将覆盖存储在凭证文件中的令牌(由 cargo-login(1) 创建)。
Cargo 配置 环境变量可用于覆盖存储在凭证文件中的令牌。crates.io 的令牌可以使用
CARGO_REGISTRY_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
键=值 或 路径- 覆盖 Cargo 配置值。参数应采用
键=值
的 TOML 语法,或作为额外配置文件的路径提供。此标志可以指定多次。有关更多信息,请参阅 命令行覆盖部分。 -C
路径- 在执行任何指定的操作之前更改当前工作目录。这会影响 cargo 默认查找项目清单 (
Cargo.toml
) 的位置,以及搜索.cargo/config.toml
等目录的位置。此选项必须出现在命令名称之前,例如cargo -C path/to/my-project build
。此选项仅在 nightly 通道 上可用,并且需要
-Z unstable-options
标志才能启用(参见 #10098)。 -h
--help
- 打印帮助信息。
-Z
标志- Cargo 的不稳定(仅限 nightly)标志。运行
cargo -Z help
获取详细信息。
环境
有关 Cargo 读取的环境变量的详细信息,请参阅参考。
退出状态
0
:Cargo 成功。101
:Cargo 未能完成。
示例
-
从索引中撤销一个 crate
cargo yank [email protected]