cargo-rail

Rust monorepo tooling for change detection, graph unification, changesets-style releases, and split/sync.

What It Covers

• plan / run: file-first change detection for selective build, test, bench, docs, and infra execution
• unify: workspace dependency unification, feature cleanup, unused dependency detection, and MSRV derivation
• release / change: Rust-native change files, per-crate bump inference, changelog generation, tags, and publish flow
• split / sync: copybara-style crate extraction and bidirectional sync without a separate DSL

Quick Start

cargo install cargo-rail

cargo rail init
cargo rail unify --check
cargo rail plan --merge-base --explain
cargo rail run --merge-base --profile ci

Pre-built binaries: GitHub Releases

Core Workflows

Change Detection

Use plan to build the deterministic contract and run to execute only the selected work.

cargo rail plan --merge-base
cargo rail plan --merge-base -f github
cargo rail run --merge-base --profile ci

impact is diagnostic. scope is the execution handoff.

Graph Unification

Use unify to keep the workspace dependency graph lean and consistent.

cargo rail unify --check
cargo rail unify --check --explain
cargo rail unify

Release Workflow

Use change for reviewed release intent and release for checks, version bumps, changelogs, tags, remote push, forge releases, and publishing.

cargo rail release check
cargo rail change add cargo-rail --bump minor --message "Added Rust-native change files for releases."
cargo rail change status
cargo rail release run cargo-rail --bump auto --check
cargo rail release run cargo-rail --bump auto --yes

Change files live in .changes/*.md by default and are consumed by release run:

---
"cargo-rail" = "minor"
---

Added Rust-native change files for releases.

--bump auto reads change files first, then falls back to conventional commits. For monorepos, commits are attributed to crates through the workspace graph instead of path-only changelog globs.

Use PR mode when version bumps and changelog text should be reviewed before tags or registry side effects:

cargo rail release run cargo-rail --bump auto --pr --yes
# after the release PR is merged, from the updated main branch:
cargo rail release finalize cargo-rail --yes

Use [release.version_groups] for crates that must release in lockstep; cargo-rail expands the group and uses the highest bump any member earned.

For owned GitHub or GitLab releases, set push = true, create_github_release = true, and choose forge = "auto", "github", or "gitlab". cargo-rail pushes the release commit and tag before creating the forge release or publishing crates.

Split / Sync

Use split and sync when a crate needs to live in both a monorepo and a standalone repository.

cargo rail split init crates/my-crate
cargo rail split run crates/my-crate
cargo rail sync crates/my-crate --to-remote

GitHub Actions

Use cargo-rail-action for planner gates and execution scope in GitHub Actions.

Config

cargo rail init
cargo rail config sync
cargo rail config validate

Primary references:

• Configuration Reference
• Command Reference
• Change Detection Guide
• Architecture

Migration

• Migrate from cargo-hakari
• Migrate from git-cliff or release-plz

Getting Help

• Issues: GitHub Issues
• Crate: crates.io/cargo-rail

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

Licensed under MIT.