cargo-release Reference

CLI Arguments

$ cargo-release release -h
Cargo subcommand for you to smooth your release process.

Usage: cargo release [OPTIONS] [LEVEL|VERSION]
       cargo release <STEP>

Steps:
  changes  Print commits since last tag
  version  Bump crate versions
  replace  Perform pre-release replacements
  hook     Run pre-release hooks
  commit   Commit the specified packages
  publish  Publish the specified packages
  owner    Ensure owners are set on specified packages
  tag      Tag the released commits
  push     Push tags/commits to remote
  config   Dump workspace configuration
  help     Print this message or the help of the given subcommand(s)

Arguments:
  [LEVEL|VERSION]  Either bump by LEVEL or set the VERSION for all selected packages [possible
                   values: major, minor, patch, release, rc, beta, alpha]

Options:
      --manifest-path <PATH>         Path to Cargo.toml
  -p, --package <SPEC>               Package to process (see `cargo help pkgid`)
      --workspace                    Process all packages in the workspace
      --exclude <SPEC>               Exclude packages from being processed
      --unpublished                  Process all packages whose current version is unpublished
  -m, --metadata <METADATA>          Semver metadata
  -x, --execute                      Actually perform a release. Dry-run mode is the default
      --no-confirm                   Skip release confirmation and version preview
      --prev-tag-name <NAME>         The name of tag for the previous release
  -c, --config <PATH>                Custom config file
      --isolated                     Ignore implicit configuration files
  -Z <FEATURE>                       Unstable options
      --sign                         Sign both git commit and tag
      --dependent-version <ACTION>   Specify how workspace dependencies on this crate should be
                                     handed [possible values: upgrade, fix]
      --allow-branch <GLOB[,...]>    Comma-separated globs of branch names a release can happen from
      --certs-source <CERTS_SOURCE>  Indicate what certificate store to use for web requests
                                     [possible values: webpki, native]
  -q, --quiet...                     Pass many times for less log output
  -v, --verbose...                   Pass many times for more log output
  -h, --help                         Print help (see more with '--help')
  -V, --version                      Print version

Commit:
      --sign-commit  Sign git commit

Publish:
      --no-publish           Do not run cargo publish on release
      --registry <NAME>      Cargo registry to upload to
      --no-verify            Don't verify the contents by building them
      --features <FEATURES>  Provide a set of features that need to be enabled
      --all-features         Enable all features via `all-features`. Overrides `features`
      --target <TRIPLE>      Build for the target triple

Tag:
      --no-tag               Do not create git tag
      --sign-tag             Sign git tag
      --tag-prefix <PREFIX>  Prefix of git tag, note that this will override default prefix based on
                             sub-directory
      --tag-name <NAME>      The name of the git tag

Push:
      --no-push             Do not run git push in the last step
      --push-remote <NAME>  Git remote to push

Bump level

• release (default): Remove the pre-release extension; if any (0.1.0-alpha.1 -> 0.1.0, 0.1.0 -> 0.1.0).
• patch:
  • If version has a pre-release, then the pre-release extension is removed (0.1.0-alpha.1 -> 0.1.0).
  • Otherwise, bump the patch field (0.1.0 -> 0.1.1)
• minor: Bump minor version (0.1.0-pre -> 0.2.0)
• major: Bump major version (0.1.0-pre -> 1.0.0)
• alpha, beta, and rc: Add/increment pre-release to your version (1.0.0 -> 1.0.1-rc.1, 1.0.1-alpha -> 1.0.1-rc.1, 1.0.1-rc.1 -> 1.0.1-rc.2)
• [version]: bump version to given version. The version has to be a valid semver string and greater than current version as in semver spec.

Configuration

Sources

Package configuration is read from the following (in precedence order)

• Command line arguments
• File specified via --config PATH
• $CRATE/Cargo.toml ([package.metadata.release] table)
• $CRATE/release.toml
• $WORKSPACE/Cargo.toml ([workspace.metadata.release] table)
• $WORKSPACE/release.toml
• platform dependent
  • linux: $HOME/.config/cargo-release/release.toml
  • windows: %FOLDERID_RoamingAppData%/cargo-release/release.toml
  • mac: $HOME/Library/Application Support/cargo-release/release.toml
• $HOME/.release.toml

Note: workspace inheritance is implicit, unlike Cargo's workspace inheritance. See also FAQ: How do I apply a setting only to one crate in my workspace?

Workspace configuration is read from the following (in precedence order)

• Command line arguments
• File specified via --config PATH
• $WORKSPACE/Cargo.toml ([workspace.metadata.release] table)
• $WORKSPACE/release.toml
• $HOME/.config/cargo-release/release.toml
• $HOME/.release.toml

Format

Summary of configuration (see below for details)

allow-branch = ["*", "!HEAD"]

sign-commit = false
sign-tag = false

release = true

shared-version = false
dependent-version = "upgrade"
metadata = "optional"

consolidate-commits = true
pre-release-replacements = []
pre-release-hook = ["..."]
pre-release-commit-message = "chore: Release"

tag = true
tag-message = "chore: Release"
tag-name = "{{prefix}}v{{version}}"
tag-prefix = "..."

push = true
push-remote = "origin"
push-options = ""

publish = true
registry = "..."
owners = []
rate-limit.new-packages = 5
rate-limit.existing-packages = 30
certs-source = "webpki"
verify = true
enable-features = []
enable-all-features = false
target = "..."

Configuration keys

Note: fields are package-configuration unless otherwise specified,

allow-branch

Workspace Configuration

• Type: list of globs
• Default: ["*", "!HEAD"]
• CLI: --allow-branch

Which branches are allowed to be released from

sign-commit

• Type: bool
• Default: false
• CLI: --sign-commit

Use GPG to sign git commits generated by cargo-release. Further information. In 0.14 sign-commit is to control signing for commit only, use sign-tag for tag signing.

If consolidate-commits = true, this is workspace-config.

sign-tag

• Type: bool
• Default: false
• CLI: --sign-tag

Use GPG to sign git tag generated by cargo-release.

release

• Type: bool
• Default: true
• CLI: --package

Release this crate (usually disabled for internal crates in a workspace)

shared-version

• Type: bool or string
• Default: false

Ensure all crates with shared-version are the same version. May also be a string to create named subsets of shared versions

dependent-version

• Type: upgrade, fix, error, warn, ignore
• Default: "upgrade"

Policy for upgrading path dependency versions within the workspace

metadata

• Type: optional, required, ignore, persistent
• Default: "optional"

Policy for presence of absence of --metadata flag when changing the version

consolidate-commits

• Type: bool
• Default: true

When releasing a workspace, use a single commit for the pre-release version bump. Commit settings will be read from the workspace-config.

pre-release-replacements

• Type: array of tables (see below)
• Default: []

Specify files that cargo-release will search and replace with new version for the release commit

This field is an array of tables with the following

• file: the file to search and replace
• search: regex that matches string you want to replace
• replace: the replacement string; you can use the any of the placeholders mentioned below. Regex patterns, such as $1, are also valid for referring to captured groups.
• min (default is 1): Minimum occurrences of search.
• max (optional): Maximum occurrences of search.
• exactly (optional): Number of occurrences of search.
• prerelease (default is false): Run the replacement when bumping to a pre-release level.

See Cargo.toml for example.

See also

• Placeholders
• FAQ: How do I update my README or other files
• FAQ: Maintaining Changelog

pre-release-hook

• Type: list of arguments

Provide a command to run before cargo-release commits version change. Placeholders can be used within the arguments. If the return code of hook command is greater than 0, the release process will be aborted.

The following environment variables are made available to pre-release-hook:

• PREV_VERSION: The version before cargo-release was executed (before any version bump).
• PREV_METADATA: The version's metadata field before cargo-release was executed (before any version bump).
• NEW_VERSION: The current (bumped) crate version.
• NEW_METADATA: The current (bumped) crate version's metadata field.
• DRY_RUN: Whether the release is actually happening (true / false)
• CRATE_NAME: The name of the crate.
• WORKSPACE_ROOT: The path to the workspace.
• CRATE_ROOT: The path to the crate.

See also

• Placeholders
• FAQ: Maintaining Changelog

pre-release-commit-message

• Type: string
• Default: "chore: Release"

A commit message template for release.

If consolidate-commits = true, this is workspace-config.

See also Placeholders

tag

• Type: bool
• Default: true
• CLI: --no-tag

Create git tag for the version

tag-message

• Type: string
• Default: "chore: Release"

A message template for an annotated tag (set to blank for lightweight tags). The placeholder {{tag_name}} and {{prefix}} (the tag prefix) is supported in addition to the global placeholders mentioned below.

See also Placeholders

tag-name

• Type: string
• Default: "{{prefix}}v{{version}}"
• CLI: --tag-name

The name of the git tag. The placeholder {{prefix}} (the tag prefix) is supported in addition to the global placeholders mentioned below.

See also

• Placeholders
• How do I customize my tagging in a workspace?

tag-prefix

• Type: string
• Default:
  • In repo root: ""
  • Otherwise: "{{crate_name}}-"
• CLI: --tag-prefix

Prefix of git tag, note that this will override default prefix based on crate name.

See also Placeholders

push

Workspace Configuration

• Type: bool
• Default: true
• CLI: --no-push

Git push the branch / tags

push-remote

Workspace Configuration

• Type: string
• Default: "origin"
• CLI: --push-remote

Default git remote to push

push-options

Workspace Configuration

• Type: list of strings

Flags to send to the server when doing a git push

publish

• Type: bool
• Default: true
• CLI: --no-publish

cargo publish right now, see manifest publish field to permanently disable publish. See release for disabling the complete release process.

registry

• Type: string
• CLI: --registry

Cargo registry name to publish to (default uses Rust's default, which goes to crates.io)

owners

• Type: list of logins
• Default: []
• CLI:

Ensure these logins are marked as owners

rate-limit.new-packages

Workspace Configuration

• Type: integer
• Default: 5

Rate limit for publishing new packages

rate-limit.existing-packages

Workspace Configuration

• Type: integer
• Default: 30

Rate limit for publishing existing packages

certs-source

• Type: webpki, native
• Default: "webpki"

Policy for using Mozilla's standard certificate root of trust (webpki) or using the system certificate root of trust (native)

verify

• Type: bool
• Default: true
• CLI: --no-verify

Verify the contents by building them

enable-features

• Type: list of names
• Default: []
• CLI: --features

Provide a set of feature flags that should be passed to cargo publish (requires rust 1.33+)

enable-all-features

• Type: bool
• Default: false
• CLI: --all-features

Signal to cargo publish, that all features should be used (requires rust 1.33+)

target

• Type: string

Target triple to use for the verification build

Placeholders

Placeholder support:

field	pre-release-replacements	pre-release-hook	pre-release-commit-message	tag-message	tag-prefix	tag-name
{{prev_version}}	yes	yes	yes if not consolidated	yes	yes	yes
{{prev_metadata}}	yes	yes	yes if not consolidated	yes	yes	yes
{{version}}	yes	yes	yes if shared or not consolidated	yes	yes	yes
{{metadata}}	yes	yes	yes if shared or not consolidated	yes	yes	yes
{{crate_name}}	yes	yes	yes if not consolidated	yes	yes	yes
{{repository}}	yes	no	no	no	no	no
{{date}}	yes	yes	yes	yes	no	no
{{prefix}}	no	no	no	no	no	yes
{{tag_name}}	no	yes	no	yes	no	no

The following placeholders are supported:

• {{prev_version}}: The version before cargo-release was executed (before any version bump).
• {{prev_metadata}}: The version's metadata before cargo-release was executed (before any version bump).
• {{version}}: The current (bumped) crate version.
• {{metadata}}: The current (bumped) crate version's metadata field.
• {{crate_name}}: The name of the current crate in Cargo.toml.
• {{repository}}: Repository of the package as defined in Cargo.toml.
• {{date}}: The current date in %Y-%m-%d format.
• {{prefix}}: The value prepended to the tag name.
• {{tag_name}}: The name of the git tag.

Environment variables

• PUBLISH_GRACE_SLEEP: sleep timeout between crates publish when releasing from workspace. This is a workaround to make previous crate discoverable on crates.io.