How to Use the Command 'cargo yank' (with examples)

The cargo yank command is a useful tool in the Rust programming ecosystem for managing the availability of crate versions on a registry like crates.io. It provides a mechanism to mark a specific version of a crate as “yanked,” which prevents new projects from automatically adopting that version when they include the crate as a dependency. This is particularly beneficial when a crate version is found to be broken or flawed after being published. Importantly, it does not delete the version—existing projects that depend on it will still function, but it will no longer be the default picked up by new projects. The command also allows for “undoing” a yank, which restores the version’s availability for new projects should the maintainer choose to do so.

Yank the Specified Version of a Crate

Code:

cargo yank crate@version

Motivation: In software development, especially when dealing with public or open-source libraries, it is not uncommon to inadvertently publish a version of a crate that contains critical bugs or issues. In such situations, continuing to allow new projects to depend on this flawed version poses a risk to those projects. By using the cargo yank command, a developer can prevent this flawed version from being selected by default for new dependencies, thereby protecting users from encountering these known issues.

Explanation:

• cargo yank: This is the main command used to mark a specific version of a crate as yanked.
• crate@version: This argument specifies the name of the crate and the specific version that you wish to yank. For example, if the crate is named “example” and the broken version is “1.0.0”, you would use example@1.0.0.

Example Output: Upon executing this command, you won’t see a detailed output like with some other commands. Instead, you will often see confirmation or acknowledgment that the operation was successful. If successful, users will notice that this version is no longer automatically used for dependencies in new projects.

    Yanked version `1.0.0` of crate `example`

Undo a Yank (Allow Downloading It Again)

Code:

cargo yank --undo crate@version

Motivation: There may be situations where a yanked version of a crate should be reinstated. Perhaps the issue that led to the initial yank has been resolved or was found to be benign, and the crate maintainer wishes to make the version available for new dependencies once more. In such cases, the undo feature allows maintainers to revert the yanking of the version efficiently.

Explanation:

• cargo yank: As before, this is the primary command, now being used with an additional flag.
• --undo: This flag is used to indicate that the yank operation should be reversed. By supplying this flag, you signal that you want to make the specified crate version available again for new projects.
• crate@version: Specifies the crate’s name and version that you wish to make available again. Continuing from the previous example, this would be example@1.0.0.

Example Output: Successful execution restores the mentioned version, with output confirming it has been undone.

    Un-yanked version `1.0.0` of crate `example`

Use the Specified Registry

Code:

cargo yank --registry name crate@version

Motivation: Rust’s package manager, Cargo, supports multiple registries. Although crates.io is the default, sometimes it is beneficial to yank a crate version in a different registry, such as an internal or private one used in enterprises. This command variant allows developers to specify which registry should be affected by the yank command, accommodating a broader range of distribution scenarios.

Explanation:

• cargo yank: The core command function remains consistent with previous uses.
• --registry name: This argument allows the user to specify a particular registry where the version should be yanked. The “name” provided must correspond to a defined registry name in the user’s Cargo configuration file.
• crate@version: As before, this specifies which version of which crate needs to be yanked.

Example Output: A successful execution will confirm that the specified version was yanked from the specified registry.

    Yanked version `1.0.0` of crate `example` from registry `private-registry`

Conclusion

The cargo yank command is a crucial tool for crate maintainers to manage the versions of crates available to users, enabling control over which versions new projects can depend on. Whether stopping the use of a faulty version, reversing a yank decision, or working within different registries, understanding how to apply these commands correctly ensures better dependency management and overall project stability in Rust development.