### Install cargo-release

Source: https://github.com/crate-ci/cargo-release/blob/master/README.md

Install the cargo-release tool using cargo.

```console
$ cargo install cargo-release
```

--------------------------------

### Cargo.toml Configuration Example

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/configuration.md

Example of how to configure cargo-release in Cargo.toml for both workspace-wide and package-specific settings.

```toml
[workspace]
# Workspace-wide release configuration
[workspace.metadata.release]
sign-commit = true
publish = false

[package]
# Package-specific release configuration
[package.metadata.release]
tag = false
```

--------------------------------

### Example Cargo-Release Configuration

Source: https://github.com/crate-ci/cargo-release/blob/master/docs/reference.md

This TOML snippet demonstrates a typical configuration for cargo-release, including branch restrictions, signing options, and release behavior.

```toml
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 = "..."

```

--------------------------------

### Cargo-Release Documentation Structure

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Illustrates the hierarchical structure of the cargo-release documentation, mapping README files to configuration, getting started, types, errors, and API reference modules.

```markdown
README (overview)
  ├─ configuration.md (user config)
  ├─ getting-started.md (lib usage)
  ├─ types.md (type ref)
  ├─ errors.md (error ref)
  └─ api-reference/
      ├─ config-module.md
      ├─ ops-modules.md
      ├─ steps-modules.md
      └─ version-module.md
```

--------------------------------

### Example Constraints for Replacements

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/errors.md

Illustrates TOML configurations for setting minimum, exact, or range constraints on regex matches during file replacements.

```toml
# Must match at least once
search = "Version: [0-9.]+"
min = 1
```

```toml
# Must match exactly twice
search = "foo"
exactly = 2
```

```toml
# Must match 1-3 times
search = "bar"
min = 1
max = 3
```

--------------------------------

### git_version

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/ops-modules.md

Verifies that Git is installed and functional on the system. This is a prerequisite for most other git operations.

```APIDOC
## git_version

### Description
Verifies git is available and functional.
```

--------------------------------

### Basic Release Operation Example

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/getting-started.md

Demonstrates the fundamental steps for using cargo-release as a library: loading workspace metadata, release configuration, verifying git status, and planning release steps. Ensure you have `cargo_metadata` and `cargo_release` as dependencies.

```rust
use cargo_release::{config, steps};
use cargo_metadata::MetadataCommand;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Get workspace metadata
    let ws_meta = MetadataCommand::new()
        .manifest_path("Cargo.toml")
        .exec()?;

    // 2. Load release configuration
    let args = config::ConfigArgs::default();
    let ws_config = config::load_workspace_config(&args, &ws_meta)?;

    // 3. Verify git is clean
    steps::verify_git_is_clean(
        Path::new("."),
        false,  // not dry-run
        log::Level::Error,
    )?;

    // 4. Load release plans
    let packages = steps::plan::load(&args, &ws_meta)?;

    // 5. Apply shared version constraints
    let packages = steps::plan::plan(packages)?;

    println!("Ready to release {} packages", packages.len());

    Ok(())
}

```

--------------------------------

### User Confirmation Prompt Example

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/errors.md

Demonstrates a Rust function call that prompts the user for confirmation before proceeding with an action like committing changes. It returns Ok(()) for confirmation or Err(0) for denial.

```rust
// Prompts "Commit ...? [y/N]"
// Returns Ok(()) if 'y', Err(0) if 'n'
confirm("Commit", &pkgs, false, false)?;
```

--------------------------------

### Get Pre-Release Replacements

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves an array of file search/replace patterns to be applied before the release process.

```rust
pub fn pre_release_replacements(&self) -> &[Replace]
```

--------------------------------

### Create Git Tag

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/README.md

Create a Git tag using `cargo_release::ops::git::tag`. This example shows how to tag a specific version with a message.

```rust
use cargo_release::ops::git;

git::tag(Path::new("."), "v1.2.3", "Release", false, false)?;
```

--------------------------------

### BumpLevel Bump Version Method Example

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/steps-modules.md

Performs an in-place version bump according to the BumpLevel. Handles major, minor, patch, release, and pre-release phase increments or stripping. Appends optional build metadata.

```rust
let mut v = semver::Version::parse("1.2.3-alpha.1")?;
BumpLevel::Release.bump_version(&mut v, None)?;
assert_eq!(v.to_string(), "1.2.3");
```

--------------------------------

### Get Pre-Release Hook Command

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the optional command to be executed before the release process begins.

```rust
pub fn pre_release_hook(&self) -> Option<&Command>
```

--------------------------------

### Get Push Options

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Provides an iterator over any additional options to be passed to the `git push` command.

```rust
pub fn push_options(&self) -> impl Iterator<Item = &str>
```

--------------------------------

### Minimal Workspace Release Configuration

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/configuration.md

This minimal configuration uses all default settings for a workspace release. It's a safe starting point when no specific overrides are needed.

```toml
[workspace.metadata.release]
```

--------------------------------

### Perform File Replacements

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/README.md

Perform file replacements using `cargo_release::ops::replace::do_file_replacements`. This example sets up a template with version and crate name for replacements.

```rust
use cargo_release::ops::replace::{do_file_replacements, Template};

let template = Template {
    version: Some("1.2.3"),
    crate_name: Some("my-crate"),
    ..Default::default()
};

do_file_replacements(&replacements, &template, Path::new("."), false, true, false)?;
```

--------------------------------

### Create New Default Config

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Instantiates a new `Config` with all fields set to their default 'None' or 'false' values. Useful for starting with a minimal configuration.

```rust
pub fn new() -> Self
```

```rust
let config = Config::new();
assert!(!config.release());
```

--------------------------------

### Verbose Logging with Cargo Release

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/errors.md

Examples of enabling debug and trace logs using the -v flag or RUST_LOG environment variable.

```bash
cargo release -v       # Debug logs
```

```bash
cargo release -vv      # Trace logs
```

```bash
RUST_LOG=debug cargo release
```

--------------------------------

### TargetVersion Bump Method Example

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/steps-modules.md

Computes the target version by bumping or setting an absolute version. Returns Some(version) if changed, None if no change is needed.

```rust
let target = TargetVersion::Relative(BumpLevel::Minor);
let current = semver::Version::parse("1.0.0")?;
let new = target.bump(&current, None)?;
assert_eq!(new.unwrap().full_version.to_string(), "1.1.0");
```

--------------------------------

### Apply Pre-release File Replacements

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/getting-started.md

Applies replacements to files based on a configuration, typically used for updating version numbers or other placeholders before a release. This example updates the README.md file with a new version. Ensure the `Replace` struct and `Template` are correctly defined.

```rust
use cargo_release::ops::replace::{Template, do_file_replacements};
use cargo_release::config::Replace;
use std::path::Path;

fn update_readme() -> Result<(), Box<dyn std::error::Error>> {
    let replacements = vec![
        Replace {
            file: "README.md".into(),
            search: r"Version: \d+\.\d+\.\d+".to_string(),
            replace: "Version: {{version}}".to_string(),
            min: Some(1),
            max: None,
            exactly: None,
            prerelease: false,
        }
    ];

    let template = Template {
        version: Some("1.2.3"),
        crate_name: Some("my-crate"),
        date: Some("2024-01-15"),
        ..Default::default()
    };

    do_file_replacements(
        &replacements,
        &template,
        Path::new("."),
        false,  // not prerelease
        true,   // verbose
        false,  // not dry-run
    )?;

    println!("Updated files");

    Ok(())
}
```

--------------------------------

### Commit All Changes with Git

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/README.md

Commit all changes in the repository using `cargo_release::ops::git::commit_all`. This example shows how to stage all changes and provide a commit message.

```rust
use cargo_release::ops::git;

git::commit_all(Path::new("."), "chore: Release", false, false)?;
```

--------------------------------

### Publish Crates with Specific Features

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/README.md

Publish crates to the registry using `cargo_release::ops::cargo::publish`. This example shows how to publish a specific crate with selective features enabled.

```rust
use cargo_release::ops::cargo::{Features, publish};

publish(false, true, Path::new("Cargo.toml"), &["my-crate"], 
        &[&Features::Selective(vec!["default".to_string()])], None, None)?;
```

--------------------------------

### Create Config with Sensible Defaults

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Initializes a `Config` with practical default values, such as enabling release, publish, and verify, and setting the push remote to 'origin'.

```rust
pub fn from_defaults() -> Self
```

```rust
let config = Config::from_defaults();
assert_eq!(config.push_remote(), "origin");
```

--------------------------------

### Step-by-Step Execution with Cargo Release

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/errors.md

Shows how to run individual steps of the cargo-release process to isolate and debug specific actions.

```bash
cargo release changes      # Show what changed
```

```bash
cargo release version      # Run version step only
```

```bash
cargo release commit       # Run commit step only
```

--------------------------------

### Get Metadata Policy

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the metadata policy for the release process. Defaults to MetadataPolicy::Optional.

```rust
pub fn metadata(&self) -> MetadataPolicy
```

--------------------------------

### Get Enabled Cargo Features

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves a list of cargo features that should be enabled during the release process.

```rust
pub fn enable_features(&self) -> &[String]
```

--------------------------------

### Dry Run vs. Execute with Cargo Release

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/errors.md

Demonstrates how to perform a dry run to preview actions and how to execute them for real.

```bash
cargo release              # Dry-run by default
```

```bash
cargo release --execute    # Actual execution
```

--------------------------------

### Config::from_defaults()

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Creates a Config instance with sensible defaults applied to all fields, such as setting 'release' and 'publish' to true, and 'push_remote' to 'origin'.

```APIDOC
## Config::from_defaults()

### Description
Creates a Config instance with sensible defaults for all fields.

### Returns
Config with default values applied (e.g., `release=true`, `publish=true`, `verify=true`, `push_remote="origin"`).

### Example
```rust
let config = Config::from_defaults();
assert_eq!(config.push_remote(), "origin");
```
```

--------------------------------

### Get Push Remote

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Returns the name of the remote repository to which changes will be pushed. Defaults to 'origin'.

```rust
pub fn push_remote(&self) -> &str
```

--------------------------------

### Typical Release Flow with Version Increment

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/version-module.md

Demonstrates incrementing minor versions, adding build metadata, and creating prereleases for subsequent versions.

```rust
use cargo_release::ops::version::VersionExt;

let mut current = semver::Version::parse("1.0.0")?;

// Stable release
current.increment_minor();
// Result: 1.1.0

// Add build info
current.metadata("build.20240101")?;
// Result: 1.1.0+build.20240101

// Prerelease for next version
current.increment_major();
current.increment_alpha()?;
// Result: 2.0.0-alpha.1
```

--------------------------------

### current_branch

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/ops-modules.md

Gets the current branch name of the repository. This function returns the shorthand name of the active branch.

```APIDOC
## current_branch

### Description
Gets current branch name.

### Parameters
#### Path Parameters
- **dir** (`&Path`) - Required - Repository directory

### Returns
Branch shorthand name.

### Example
```rust
let branch = git::current_branch(Path::new("."))?;
println!("On branch: {}", branch);
```
```

--------------------------------

### RateLimit::from_defaults() Method

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Creates a `RateLimit` configuration initialized with the default values recommended by crates.io: 5 for new packages and 30 for existing packages.

```rust
pub fn from_defaults() -> Self
```

--------------------------------

### Get Registry Name

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Returns the name of the cargo registry to publish to, if specified. Returns `None` if not set.

```rust
pub fn registry(&self) -> Option<&str>
```

--------------------------------

### Prerelease Progression with Version Steps

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/version-module.md

Illustrates the progression through different prerelease stages (alpha, beta, rc) before a final release.

```rust
let mut v = semver::Version::parse("1.0.0")?;

// Alpha phase
v.increment_alpha()?;  // 1.0.1-alpha.1
v.increment_alpha()?;  // 1.0.1-alpha.2

// Progress to beta
v.increment_beta()?;   // 1.0.1-beta.1

// Final rc
v.increment_rc()?;     // 1.0.1-rc.1

// Release
v.increment_patch();   // 1.0.1
```

--------------------------------

### Get Certificate Source for HTTPS

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the certificate source configuration for HTTPS connections. Defaults to CertsSource::Webpki.

```rust
pub fn certs_source(&self) -> CertsSource
```

--------------------------------

### Get Crate Owners

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Returns a slice of strings representing the required crate owners. Defaults to an empty list.

```rust
pub fn owners(&self) -> &[String]
```

--------------------------------

### Steps & Planning API

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/FILES.txt

Documentation for the steps and planning module, including verification functions, planning functions, and related enums and structs.

```APIDOC
## Steps & Planning Module

### Description
Covers functions related to the verification and planning stages of the release process, including definitions for target versions and bump levels.

### API Surface
- **Verification Functions**: 8 functions for validating release steps.
- **Planning Functions**: 5 functions for planning the release process.
- **Enums**: `TargetVersion`, `BumpLevel`.
- **Structs**: `PackageRelease`, `Version`.

### Usage
Consult `api-reference/steps-modules.md` for comprehensive details on these functions and types.
```

--------------------------------

### Get Dependent Version Update Policy

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the policy for handling dependent version updates. Defaults to DependentVersion::Upgrade.

```rust
pub fn dependent_version(&self) -> DependentVersion
```

--------------------------------

### Use a Custom Configuration File

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/configuration.md

Specify a custom TOML file for cargo-release configuration using the -c flag.

```bash
cargo release -c custom.toml

```

--------------------------------

### Configure Pre-Release Hook Command

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/configuration.md

Specify a command to run before release steps. The command runs in the package directory and its failure will abort the release. Can be a single string or a list of strings for complex commands.

```toml
pre-release-hook = "cargo test --release"
```

```toml
pre-release-hook = ["bash", "-c", "cargo test --release"]
```

--------------------------------

### Verify Cargo Release Configuration

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/README.md

Use `--dry-run` to check your configuration without making any changes. This is useful for verifying settings before a real release.

```bash
cargo release --dry-run
```

--------------------------------

### Get Current Git Branch

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/ops-modules.md

Retrieves the name of the current git branch. Useful for conditional logic based on the active branch.

```rust
let branch = git::current_branch(Path::new("."))?;
println!("On branch: {}", branch);
```

--------------------------------

### Config::push_options()

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Returns an iterator over the options that should be passed to 'git push'.

```APIDOC
## Config::push_options()

### Description
Returns an iterator of push options passed to git push.

### Returns
Iterator over push option strings.
```

--------------------------------

### RateLimit::new() Method

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Creates an empty `RateLimit` configuration, allowing for custom limits to be set later.

```rust
pub fn new() -> Self
```

--------------------------------

### Get Full Tag Name Template

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the template for the complete tag name. Defaults to "{{prefix}}v{{version}}".

```rust
pub fn tag_name(&self) -> &str
```

--------------------------------

### Get Allowed Branches

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves an iterator for allowed branch patterns. Defaults to `["*", "!HEAD"]` if not explicitly set.

```rust
pub fn allow_branch(&self) -> impl Iterator<Item = &str>
```

```rust
let config = Config::from_defaults();
let branches: Vec<&str> = config.allow_branch().collect();
assert!(branches.contains(&"*"));
```

--------------------------------

### Typical Workspace Configuration

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/README.md

A common configuration for workspaces, enabling signed commits, specifying allowed branches, consolidating commits, and configuring pre-release file replacements.

```toml
[workspace.metadata.release]
sign-commit = true
allow-branch = ["main", "release/*"]
consolidate-commits = true

[[workspace.metadata.release.pre-release-replacements]]
file = "README.md"
search = "version [0-9.]+"
replace = "version {{version}}"
```

--------------------------------

### Prerelease Configuration with Replacements

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/configuration.md

Configure prerelease settings, including tag prefixes and hooks. This snippet also demonstrates how to use prerelease-specific replacements in the CHANGELOG.md file.

```toml
[package.metadata.release]
tag-prefix = "pre-"
pre-release-hook = "cargo test --all-features"
pre-release-replacements = [
  {file = "CHANGELOG.md", search = "ReleaseDate", replace = "{{date}}", prerelease = true},
]
```

--------------------------------

### Configure Pre-Release File Replacements

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/configuration.md

Define search and replace patterns for files before a release. Supports regex matching and template variables. Use `min`, `max`, or `exactly` to control the number of replacements.

```toml
[[pre-release-replacements]]
file = "README.md"
search = "Current release: [a-z0-9\.-]+"
replace = "Current release: {{version}}"

[[pre-release-replacements]]
file = "CHANGELOG.md"
search = "Unreleased"
replace = "{{version}}"
min = 1
```

--------------------------------

### Get Pre-release Commit Message

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Returns the template for the commit message used before a pre-release. The default message varies based on whether commits are consolidated.

```rust
pub fn pre_release_commit_message(&self) -> &str
```

--------------------------------

### shell::help

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/ops-modules.md

Prints a styled help message to stderr.

```APIDOC
## shell::help

### Description
Prints styled help message.

### Parameters
#### Path Parameters
- **message** (impl Display) - Required - Message content
```

--------------------------------

### Bump Version Relative to Current

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/README.md

Bump the version relative to the current version using `TargetVersion::Relative` and `BumpLevel`. This example shows how to specify a minor version bump.

```rust
use cargo_release::steps::{TargetVersion, BumpLevel};

let target = TargetVersion::Relative(BumpLevel::Minor);
let new_version = target.bump(&current_version, None)?;
```

--------------------------------

### Set Logging Level for Cargo-Release

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/configuration.md

Control the logging output of cargo-release by setting the RUST_LOG environment variable. This example sets the log level to 'debug' for the 'cargo_release' crate.

```bash
RUST_LOG=cargo_release=debug cargo release
```

--------------------------------

### Load Configuration from Cargo.toml

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/getting-started.md

Loads the release configuration from the [package.metadata.release] section of your Cargo.toml file. Ensure cargo_metadata is available.

```rust
use cargo_release::config;
use cargo_metadata::MetadataCommand;

fn load_config() -> Result<(), Box<dyn std::error::Error>> {
    let ws_meta = MetadataCommand::new().exec()?;
    
    // Loads from Cargo.toml [package.metadata.release]
    let config = config::load_workspace_config(
        &config::ConfigArgs::default(),
        &ws_meta,
    )?;

    println!("Push to: {}", config.push_remote());
    println!("Sign commits: {}", config.sign_commit());
    println!("Publish: {}", config.publish());

    Ok(())
}
```

--------------------------------

### Run Individual Cargo Release Steps

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/configuration.md

Execute specific steps of the release process individually, such as bumping versions, applying replacements, or publishing.

```bash
cargo release version

```

```bash
cargo release replace

```

```bash
cargo release hook

```

```bash
cargo release commit

```

```bash
cargo release publish

```

```bash
cargo release tag

```

```bash
cargo release push

```

```bash
cargo release changes

```

```bash
cargo release config

```

--------------------------------

### Get Tag Prefix Template

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the tag prefix template. For non-root packages, it defaults to "{{crate_name}}-"; for the root package, it defaults to an empty string.

```rust
pub fn tag_prefix(&self, is_root: bool) -> &str
```

--------------------------------

### Get Tag Message Template

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the template string used for generating the tag message. Defaults to "chore: Release {{crate_name}} version {{version}}".

```rust
pub fn tag_message(&self) -> &str
```

--------------------------------

### Configure Logging

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/getting-started.md

Set up the env_logger for your application. This allows you to control the verbosity of logs and format them as needed.

```rust
use std::io::Write;

fn setup_logging() {
    let mut builder = env_logger::Builder::new();
    builder.filter(None, log::LevelFilter::Debug);
    builder.format_module_path(false);
    builder.init();
}
```

--------------------------------

### RateLimit::new_packages() Method

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the configured rate limit for uploading new packages. If not explicitly set, it defaults to 5.

```rust
pub fn new_packages(&self) -> usize
```

--------------------------------

### Get Cargo Features Enum

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the features enum for passing to cargo commands. Returns Features::All if all_features is true, otherwise Features::Selective or Features::None.

```rust
pub fn features(&self) -> cargo::Features
```

--------------------------------

### RateLimit::existing_packages() Method

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the configured rate limit for uploading existing packages. If not explicitly set, it defaults to 30.

```rust
pub fn existing_packages(&self) -> usize
```

--------------------------------

### Configuration API

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/FILES.txt

Documentation for the configuration module, including the Config struct, CLI arguments, accessor methods, and related enums.

```APIDOC
## Configuration Module

### Description
Provides access to all configuration options for cargo-release, including file-based configuration and command-line arguments.

### API Surface
- **Config struct**: Contains 25 fields covering various settings.
- **ConfigArgs**: Represents command-line arguments for configuration.
- **Accessor Methods**: 35+ methods for retrieving configuration values.
- **Loading Functions**: Functions to load configuration from files and arguments.
- **Enums**: `DependentVersion`, `MetadataPolicy`, `CertsSource` related to configuration.

### Usage
Refer to `api-reference/config-module.md` for detailed function signatures, parameter descriptions, and examples.
```

--------------------------------

### cargo-release CLI Help

Source: https://github.com/crate-ci/cargo-release/blob/master/docs/reference.md

Displays the help message for the cargo-release CLI, outlining available commands, arguments, and options.

```console
$ 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

```

--------------------------------

### Update Version in README and Source Files

Source: https://github.com/crate-ci/cargo-release/blob/master/docs/faq.md

Configure pre-release replacements in release.toml to update version strings in specified files. Ensure the 'search' pattern matches your crate name.

```toml
[dependencies]
predicates = "1.0.2"

```

```toml
pre-release-replacements = [
  {file="README.md", search="predicates = .\*", replace="{{crate_name}} = \"{{version}}\""},
  {file="src/lib.rs", search="predicates = .\*", replace="{{crate_name}} = \"{{version}}\""},
]

```

--------------------------------

### Confirm Before Action

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/getting-started.md

This snippet shows how to prompt the user for confirmation before proceeding with a release action. It requires confirmation by default.

```rust
use cargo_release::steps::confirm;
use cargo_release::steps::plan::PackageRelease;

fn interactive_release(pkgs: &[PackageRelease]) -> Result<(), Box<dyn std::error::Error>> {
    // Ask user for confirmation
    confirm(
        "Release",
        pkgs,
        false,  // require confirmation
        false,  // not dry-run
    )?;

    println!("User confirmed release");

    Ok(())
}
```

--------------------------------

### Use VersionExt for Advanced Version Manipulation

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/getting-started.md

Demonstrates using the `VersionExt` trait to increment release candidates and add build metadata to a semantic version.

```rust
use cargo_release::ops::version::VersionExt;
use semver::Version;

fn bump_version() -> Result<(), Box<dyn std::error::Error>> {
    let mut v = Version::parse("1.0.0")?;

    // Release candidate
    v.increment_rc()?;
    assert_eq!(v.to_string(), "1.0.1-rc.1");

    // Add metadata
    v.metadata("build.001")?;
    assert_eq!(v.to_string(), "1.0.1-rc.1+build.001");

    Ok(())
}
```

--------------------------------

### Run cargo-release in dry-run mode

Source: https://github.com/crate-ci/cargo-release/blob/master/README.md

Execute cargo-release in dry-run mode to preview actions without making changes. Use `--execute` to perform the actual release.

```console
$ cargo release [level]
<dry-run output>
```

--------------------------------

### Config::verify()

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Returns a boolean indicating whether verification should occur before publishing. Defaults to true.

```APIDOC
## Config::verify()

### Description
Returns whether to verify before publishing. Defaults to true.

### Returns
`bool` indicating if verification should be performed.
```

--------------------------------

### Config::new()

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Creates a new default Config instance with all fields set to their default initial values (typically None or false).

```APIDOC
## Config::new()

### Description
Creates a new default Config instance.

### Returns
Default Config with all fields set to None or false.

### Example
```rust
let config = Config::new();
assert!(!config.release());
```
```

--------------------------------

### Config::pre_release_hook

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the optional command to be executed before the release process begins.

```APIDOC
## Config::pre_release_hook()

### Description
Returns the optional command to run before release.

### Method
GET

### Endpoint
/config/pre_release_hook

### Returns
- `Option<&Command>` - An optional Command to execute.
```

--------------------------------

### Config::pre_release_replacements

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves an array of file search and replace patterns that are applied before a release.

```APIDOC
## Config::pre_release_replacements()

### Description
Returns an array of file search/replace patterns to apply before release.

### Method
GET

### Endpoint
/config/pre_release_replacements

### Returns
- `&[Replace]` - An array of Replace patterns.
```

--------------------------------

### Publishing to a Custom Registry

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/README.md

Configuration for publishing a package to a custom registry, specifying the registry name and owners.

```toml
[package.metadata.release]
registry = "my-registry"
owners = ["admin@example.com"]
```

--------------------------------

### Automate Changelog Replacements

Source: https://github.com/crate-ci/cargo-release/blob/master/docs/faq.md

Configure pre-release replacements in release.toml to automate updates to a hand-written CHANGELOG.md, following the Keep a Changelog format. This involves replacing placeholders like 'Unreleased', 'ReleaseDate', and URL components with dynamic variables.

```markdown
<!-- next-header -->

## [Unreleased] - ReleaseDate

### Added
- feature 3

### Changed
- bug 1

## [1.0.0] - 2017-06-20
### Added
- feature 1
- feature 2

<!-- next-url -->
[Unreleased]: https://github.com/assert-rs/predicates-rs/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/assert-rs/predicates-rs/compare/v0.9.0...v1.0.0

```

```toml
pre-release-replacements = [
  {file="CHANGELOG.md", search="Unreleased", replace="{{version}}"},
  {file="CHANGELOG.md", search="\.\.\.HEAD", replace="...{{tag_name}}", exactly=1},
  {file="CHANGELOG.md", search="ReleaseDate", replace="{{date}}"},
  {file="CHANGELOG.md", search="<!-- next-header -->", replace="<!-- next-header -->\n\n## [Unreleased] - ReleaseDate", exactly=1},
  {file="CHANGELOG.md", search="<!-- next-url -->", replace="<!-- next-url -->\n[Unreleased]: {{repository}}/compare/{{tag_name}}...HEAD", exactly=1},
]

```

--------------------------------

### Version Increment with Configurable Metadata Policy

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/version-module.md

Shows how to conditionally add metadata based on a policy, illustrating both optional and required metadata scenarios.

```rust
let mut v = semver::Version::parse("1.0.0")?;
let metadata = Some("git.abc123");

// Optional policy: add if provided
v.increment_minor();
if let Some(m) = metadata {
    v.metadata(m)?;
}
// Result: 1.1.0+git.abc123 (if metadata provided)

// Required policy: must provide
if metadata.is_none() {
    return Err("metadata required".into());
}
```

--------------------------------

### CertsSource Enum

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Selects the certificate store to use. Defaults to Mozilla's Webpki store, with an option for the system's Native store.

```rust
pub enum CertsSource {
    Webpki,  // Mozilla's root certificate store (default)
    Native,  // System root certificate store
}
```

--------------------------------

### ConfigArgs::to_config() Method Signature

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Signature for converting ConfigArgs into a Config object. Returns a Config.

```rust
pub fn to_config(&self) -> Config
```

--------------------------------

### Load Workspace Configuration

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/README.md

Load the workspace configuration using `cargo_release::config::load_workspace_config`. This requires `cargo_metadata::MetadataCommand` to be executed first.

```rust
use cargo_release::config;
use cargo_metadata::MetadataCommand;

let ws_meta = MetadataCommand::new().exec()?;
let config = config::load_workspace_config(
    &config::ConfigArgs::default(),
    &ws_meta,
)?;
```

--------------------------------

### Config::publish()

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Returns a boolean indicating whether the release should be published. Defaults to true.

```APIDOC
## Config::publish()

### Description
Returns whether to publish. Defaults to true.

### Returns
`bool` indicating if the release should be published.
```

--------------------------------

### List Package Contents

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/ops-modules.md

Lists all files that would be included in a cargo package by running `cargo package --list`.

```rust
let files = cargo::package_content(Path::new("Cargo.toml"))?;
println!("Package contains {} files", files.len());
```

--------------------------------

### ConfigArgs Struct

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Defines command-line arguments for configuration. Used to construct a Config object.

```rust
pub struct ConfigArgs {
    pub custom_config: Option<PathBuf>,
    pub isolated: bool,
    pub z: Vec<UnstableValues>,
    pub sign: bool,
    pub no_sign: bool,
    pub dependent_version: Option<DependentVersion>,
    pub allow_branch: Option<Vec<String>>,
    pub certs_source: Option<CertsSource>,
    pub commit: CommitArgs,
    pub publish: PublishArgs,
    pub tag: TagArgs,
    pub push: PushArgs,
}
```

--------------------------------

### Execute Command with Environment Variables

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/ops-modules.md

Executes a command with a custom set of environment variables.

```rust
pub fn call_with_env(cwd: &Path, cmd: &[&str], env: &[(String, String)]) -> CargoResult<()>
```

--------------------------------

### Build Custom Configuration

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/getting-started.md

Creates a custom `Config` object programmatically. Useful for overriding settings or when not using Cargo.toml.

```rust
use cargo_release::config::Config;

fn custom_config() -> Config {
    Config {
        is_workspace: false,
        release: Some(true),
        publish: Some(false),  // Don't publish
        sign_commit: Some(true),
        push_remote: Some("upstream".to_string()),
        allow_branch: Some(vec!["main".to_string(), "release/*".to_string()]),
        ..Default::default()
    }
}
```

--------------------------------

### Publish Packages

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/getting-started.md

Use this snippet to publish a crate with specified features. It performs a dry-run and verification.

```rust
use cargo_release::ops::cargo::{Features, publish};
use std::path::Path;

fn publish_crate() -> Result<(), Box<dyn std::error::Error>> {
    let features = &[&Features::Selective(vec!["default".to_string()])];

    let success = publish(
        false,  // not dry-run
        true,   // verify
        Path::new("Cargo.toml"),
        &["my-crate"],
        features,
        None,   // default registry
        None,   // no target
    )?;

    println!("Published: {}", success);

    Ok(())
}
```

--------------------------------

### Config::tag()

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Returns a boolean indicating whether git tags should be created for the release. Defaults to true.

```APIDOC
## Config::tag()

### Description
Returns whether to create git tags. Defaults to true.

### Returns
`bool` indicating if git tags should be created.
```

--------------------------------

### Check Tag Creation Enabled

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Determines whether git tags should be created for the release. Defaults to `true`.

```rust
pub fn tag(&self) -> bool
```

--------------------------------

### Steps and Orchestration API Reference

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Reference for the steps and orchestration API, detailing verification and planning functions, version targeting, bump levels, and planning structures.

```APIDOC
## Steps and Orchestration API Reference

### Description
Reference for the steps and orchestration API, detailing verification and planning functions, version targeting, bump levels, and planning structures.

### Key Components
- **Verification functions**: 8 functions for checking git state, versions, metadata, and rate limits.
- **Planning functions**: Handle shared versions, consolidation, changes detection, and user confirmation.
- **TargetVersion enum**: Defines relative vs. absolute version targeting with bump computation.
- **BumpLevel enum**: Specifies release stages (Major, Minor, Patch, Release, RC, Beta, Alpha) for in-place bumping.
- **Step submodules**: Define the structure of individual release steps.
- **plan module**: Contains `PackageRelease`, `Version`, `Dependency`, and related planning functions.
```

--------------------------------

### Command::args() Method

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Retrieves the command as a vector of string slices. For a `Line` command, it returns a single-element vector. For an `Args` command, it returns all provided arguments.

```rust
pub fn args(&self) -> Vec<&str>
```

--------------------------------

### Configure Rate Limits for Publishing

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/configuration.md

Set rate limits for publishing new and existing packages to crates.io. These settings help manage publishing frequency according to crates.io's enforced limits.

```toml
[workspace.metadata.release.rate-limit]
new-packages = 5
existing-packages = 30

```

--------------------------------

### load_workspace_config

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Loads workspace configuration by merging defaults, Cargo.toml metadata, custom config files, and command-line overrides.

```APIDOC
## load_workspace_config

### Description
Loads workspace configuration from files and command-line arguments. It merges configuration from multiple sources, starting with defaults and applying overrides.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
N/A (Function Call)

### Endpoint
N/A (Function Call)

### Parameters
- **args** (`&ConfigArgs`) - Required - Command-line arguments
- **ws_meta** (`&cargo_metadata::Metadata`) - Required - Cargo workspace metadata

### Returns
Merged configuration.
```

--------------------------------

### ReleaseOpt Struct Definition

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/types.md

Defines the options for the Release command, including release steps, logging verbosity, and optional step overrides.

```rust
pub struct ReleaseOpt {
    pub release: steps::release::ReleaseStep,
    pub logging: Verbosity,
    pub step: Option<Step>,
}
```

--------------------------------

### Create Git Commit and Tag

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/getting-started.md

Creates a Git commit with a specified message and then creates a Git tag for a release. This function requires the path to the repository directory. Ensure that `sign` and `dry_run` parameters are set appropriately for your needs.

```rust
use cargo_release::ops::git;
use std::path::Path;

fn release_git(dir: &Path) -> Result<(), Box<dyn std::error::Error>> {
    // Create commit
    if git::commit_all(
        dir,
        "chore: Release v1.2.3",
        false,  // sign
        false,  // not dry-run
    )? {
        println!("Committed");
    } else {
        println!("Nothing to commit");
    }

    // Create tag
    if git::tag(
        dir,
        "v1.2.3",
        "Release version 1.2.3",
        false,  // sign
        false,  // not dry-run
    )? {
        println!("Tagged");
    }

    Ok(())
}
```

--------------------------------

### VersionExt::increment_beta

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/version-module.md

Increments or switches the version to a beta pre-release. If the version is already beta, it increments the beta counter. If there is no pre-release, it switches to beta.1 (incrementing patch first). If the version is alpha, it switches to beta.1. Errors if attempting to downgrade from rc. Clears build metadata.

```APIDOC
## VersionExt::increment_beta

### Description
Increments or switches to beta pre-release. If already beta, increments counter. If no pre-release, switches to beta.1 (increments patch first). If alpha, switches to beta.1. Errors if trying to downgrade from rc. Clears build metadata.

### Method
`fn increment_beta(&mut self) -> CargoResult<()>`

### Returns
Ok(()) on success, Err if trying to downgrade from rc to beta.

### Example
```rust
// No pre-release → beta.1
let mut v = semver::Version::parse("1.2.3")?;
v.increment_beta()?;
assert_eq!(v.to_string(), "1.2.4-beta.1");

// Alpha → beta.1
let mut v = semver::Version::parse("1.2.3-alpha.1")?;
v.increment_beta()?;
assert_eq!(v.to_string(), "1.2.3-beta.1");

// Beta → beta.2
let mut v = semver::Version::parse("1.2.3-beta.1")?;
v.increment_beta()?;
assert_eq!(v.to_string(), "1.2.3-beta.2");
```
```

--------------------------------

### Config::push()

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Returns a boolean indicating whether to push changes after the release. Defaults to true.

```APIDOC
## Config::push()

### Description
Returns whether to push changes. Defaults to true.

### Returns
`bool` indicating if changes should be pushed.
```

--------------------------------

### Execute Command

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/ops-modules.md

Executes a command and waits for its completion using the cmd module.

```rust
pub fn call(cmd: &[&str]) -> CargoResult<()>
```

--------------------------------

### Config::enable_all_features

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Determines whether to use the '--all-features' flag for cargo commands. Defaults to false.

```APIDOC
## Config::enable_all_features()

### Description
Returns whether to use --all-features.

### Method
GET

### Endpoint
/config/enable_all_features

### Returns
- `bool` - True if --all-features should be used, false otherwise.
```

--------------------------------

### Config::allow_branch()

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/api-reference/config-module.md

Returns an iterator over the allowed branch patterns for releases. Defaults to `["*", "!HEAD"]`.

```APIDOC
## Config::allow_branch()

### Description
Returns an iterator of allowed branch patterns. Defaults to `["*", "!HEAD"]`.

### Returns
Iterator over allowed branch glob patterns.

### Example
```rust
let config = Config::from_defaults();
let branches: Vec<&str> = config.allow_branch().collect();
assert!(branches.contains(&"*"));
```
```

--------------------------------

### Replace Struct for Pre-release Updates

Source: https://github.com/crate-ci/cargo-release/blob/master/_autodocs/types.md

Specifies a file, search pattern, and replacement string for updating files during pre-release versioning. Supports optional minimum, maximum, and exact match counts.

```rust
pub struct Replace {
    pub file: PathBuf,
    pub search: String,
    pub replace: String,
    pub min: Option<usize>,
    pub max: Option<usize>,
    pub exactly: Option<usize>,
    pub prerelease: bool,
}
```

--------------------------------

### Execute cargo-release with execution flag

Source: https://github.com/crate-ci/cargo-release/blob/master/README.md

Run cargo-release with the `--execute` flag to perform the release process after a dry run.

```console
$ cargo release [level] --execute
```