cargo-rail

Replace the Rust workspace maintenance stack with one graph-aware Cargo tool.

cargo-rail unifies dependencies, selects affected CI work, releases crates, and maintains standalone crate repositories from the same Cargo graph and git history.

One binary. One rail.toml. No hosted service, workspace-hack crate, embedded git implementation, or separate workflow runtime.

Replace the stack

Replace	With
cargo-hakari, dependency-unification scripts	cargo rail unify
cargo-udeps, cargo-shear, cargo-machete	Built-in compiler-backed unused-dependency detection and removal
cargo-unused-features, cargo-features-manager, cargo-autoinherit, cargo-msrv, feature-audit scripts	Dead-feature pruning, borrowed-feature repair, inheritance enforcement, and MSRV computation
release-plz, cargo-release, git-cliff	cargo rail change + cargo rail release
dorny/paths-filter, path globs, package-selection scripts	cargo rail plan + cargo rail run
Hand-maintained publish ordering	Dependency-ordered workspace releases
Copybara, git subtree, split/sync scripts	cargo rail split + cargo rail sync

These are not disconnected wrappers. Every workflow consumes the same resolved workspace model, so a dependency change can select CI work, drive a release, order publication, and remain traceable into a standalone repository.

Install

cargo install cargo-rail
cargo rail init
cargo rail config validate --strict

Pre-built native archives for x86-64/ARM64 GNU/Linux, Windows MSVC, and macOS, plus cross-built musl Linux archives, SHA-256 checksums, and signed provenance are available from GitHub Releases. cargo-binstall cargo-rail is supported.

After an upgrade, run cargo rail config migrate --check. Exit 1 means an explicit semantic migration is available; review it, apply it with cargo rail config migrate, then validate. Coded defaults are never copied into rail.toml.

Unify

Make workspace manifests agree. unify detects version drift, fragmented features, unused dependencies, dead features, undeclared feature borrowing, and MSRV mismatches. It can replace a generated workspace-hack crate with explicit workspace dependencies.

Unused-edge decisions combine Cargo's resolved graph with workspace-only rustc evidence across configured targets and source-derived feature selections. Results are cached by compilation-unit identity, and apply revalidates the exact manifest edits and portable graph delta before committing them. Destructive cleanup of dormant private features and optional dependencies requires consumer_scope = "workspace"; published packages remain open-world.

cargo rail unify --check --explain  # inspect every decision
cargo rail unify doctor             # inspect resolver/target/alias hazards
cargo rail unify                    # apply the plan
cargo rail unify undo               # restore the last backup

The check path does not mutate manifests and exits non-zero when changes are needed. Compiler analysis may update cache and report files under target/cargo-rail/.

Change detection

Turn git changes into an executable Cargo scope. plan maps files to owning crates, walks reverse dependencies, classifies build, test, docs, bench, and infrastructure surfaces, then emits a stable machine-readable contract.

cargo rail plan --merge-base --explain
cargo rail run --merge-base --profile ci
cargo rail doctor hermeticity --profile ci

Use run directly or feed plan -f github into existing CI jobs. No duplicated package-selection logic and no path-filter graph to keep synchronized with Cargo.

Hermeticity diagnosis hashes only the selected source and dependency closure, resolved features and targets, effective Cargo settings, toolchain/wrapper chain, argv, and typed environment. It reports every incomplete ambient, build-script, proc-macro, external-tool, or dependency-result boundary and withholds an ActionKey until none remain. That identity also authorizes verified local reuse for the classes that have earned it. The isolated whole-action cache remains limited to supported current-host macOS cargo check actions. Ordinary non-incremental build (cargo check) and distribution (cargo build --release) actions can additionally reuse verified dependency and workspace library metadata/rlib results across clean roots for the exact toolchain certificates in the generated capability matrix. The native cache is machine-local, preserves existing compiler wrappers and sccache, and executes every unproven compiler class cold with an explicit reason. Linked binaries, tests, proc macros, build scripts, native linking, custom targets, and unqualified toolchains are not cached.

Enable the graduated native class explicitly through Cargo's non-incremental boundary:

cargo rail doctor native-cache --format json
CARGO_INCREMENTAL=0 cargo rail run --all --action build --explain
CARGO_INCREMENTAL=0 cargo rail run --all --action distribution --explain

Interleaved 110-sample fixture measurements reduced warm clean-root p50 versus native Cargo by 29.2%/26.4% for checks/release builds on macOS ARM64, 41.3%/39.9% on Linux x86-64, and 37.2%/37.5% on Linux ARM64. Against sccache 0.16.0, cargo-rail was 5.7%/6.6% faster on macOS, 8.7% slower/10.9% faster on Linux x86-64, and 0.7% slower/11.4% faster on Linux ARM64. These are same-host fixture results, not universal performance claims. Windows x86-64 remains unqualified.

See Caching for activation, telemetry, benchmark evidence, and cleanup.

Release

Record release intent in the pull request that introduces the change. Reviewed .changes/ entries are the default and sole source of automatic bumps and release prose; conventional commits are available only through explicit compatibility modes. Dependency cascades remain synthesized by cargo-rail.

cargo rail change add my-crate --bump minor --message "Added graph-aware planning."
cargo rail change add my-crate --bump none --message "Internal refactor; no released behavior changed."
cargo rail change check --merge-base
cargo rail release run --all --pr --check

After the release PR merges:

cargo rail release finalize --all --yes

Release execution is journaled as planned → prepared → awaiting_checks → ready → publishing → released. A plan-bound Rail-Release trailer identifies every release commit. For remote releases, cargo-rail pushes the exact commit first and exits without polling. GitHub readiness requires at least one completed successful, non-skipped context, no pending or failed context, and complete context counts; GitLab requires a successful exact-SHA pipeline. After readiness is proven, cargo-rail publishes packages in dependency order and creates/pushes tags only after every required version is observable. Inspect interruption or convergence state without loading Cargo metadata:

cargo rail release status
cargo rail release resume target/cargo-rail/releases/release-<id>.json
# In another checkout with no journal:
cargo rail release resume release-<transaction-id>

cargo rail clean refuses active or ambiguous release state and prunes terminal journals. Optional cargo-semver-checks analysis validates reviewed intent: a confirmed breaking change with an insufficient entry blocks and returns the plan to the author instead of silently escalating the bump.

Split and sync

Develop crates in a monorepo and publish them from focused standalone repositories. split filters crate history and rewrites workspace-relative manifests; sync maps later commits in either direction.

cargo rail split init my-crate
cargo rail split run my-crate --check
cargo rail split run my-crate
cargo rail sync my-crate --to-remote

Conflicts use explicit manual, ours, theirs, or union strategies with resumable receipts. Copybara configuration and subtree choreography are unnecessary.

Why one tool?

Cargo already owns the package graph. Git already owns change history. cargo-rail uses those sources directly instead of rebuilding partial models in a collection of plugins, actions, bots, and shell scripts.

The result is one install graph, one configuration surface, and one set of decisions to inspect. See the architecture for the internal model and the planner contract for its stable CI interface.

Commands

Command	Purpose
init	Create or update rail.toml
unify	Inspect and repair workspace dependency state
plan / run	Select and execute work affected by a change
change / release	Review release intent and run graph-ordered releases
split / sync	Maintain standalone repositories from monorepo crates
doctor, config, graph, hash	Inspect action/toolchain cache proof, validate configuration, and explain planner state

Documentation

• Configuration reference
• Command reference
• Caching and evaluation
• Generated execution, cache, and performance support matrix
• Change detection
• Planner machine contract
• Migrate from cargo-hakari
• Migrate from git-cliff or release-plz
• Split/sync example

Project

cargo-rail is actively maintained, requires Rust 1.95.0 or newer, and is licensed under MIT.

• Contributing
• Security policy
• Issue tracker