cargo-rail

A deterministic, cargo-native control plane for Rust monorepos: build/check/test/bench only what changes locally and in CI, unify the graph (deps/features), split/sync crates into new repos/monorepos, and automate releases with 14 core dependencies.

Why

Documented change-detection impact on real repos (tokio, helix, meilisearch, helix-db):

Compounding effects = massive time/cost savings:

1. Change Detection (plan/run) reduces what runs — 68% of measured commits avoided full-run behavior, with explicit plan traces.
2. Dependency Unification (unify) reduces build graph complexity — cleaner deps, smaller build units, fewer rebuilds
3. Smaller Build Graphs cargo-rail uses 14 core-deps for automatically removing unused dependencies, pruning truly dead features, unifying undeclared features, computing MSRV, splitting and synching crate/s to new, clean repos, and the entire release workflow w/ changelog generation. This results in fewer tools and less cargo-metadata fetches.

Before cargo-rail: Run 6 tools separately (hakari and/or workspace-hack, udeps, machete, shear, features-manager, msrv, sort, and more), each with different data/timing After cargo-rail: cargo rail unify --check in one metadata call

Quick Start

# install
cargo install cargo-rail

# generate config
cargo rail init

# dependency hygiene
cargo rail unify --check

# deterministic planning + execution
cargo rail plan --merge-base
cargo rail run --merge-base --profile ci
cargo rail plan --merge-base --explain

Pre-built binaries: GitHub Releases

Workflows

Change Planning (detection) + Execution (plan / run)

Problem: CICD wastes resources testing unchanged code. We either (1) test everything on every commit, or (2) build custom scripts that drift from local behavior.

Solution: One planner contract, used everywhere:

# Local: what would CI run if I pushed this branch?
cargo rail plan --merge-base

# CI: deterministic plan → selective execution
cargo rail plan --merge-base -f github  # outputs: build=true, test=false, docs=true, ...
cargo rail run --merge-base --profile ci  # runs ONLY what plan selected

How to use this effectively:

1. Configure change detection rules in .config/rail.toml (infrastructure files, doc-only changes, custom, etc.)
2. Run plan to see impact classification (which surfaces: build, test, bench, docs, infra, custom)
3. Run run to execute only selected surfaces — locally or in CI - or wire to justfile, makefile, xtask, or shell scripts.
4. Use --explain to understand any decision: "why did this run?" / "why was this skipped?"

Result: 21% build skip, 19% test skip, 68% targeted/non-full runs across 80 measured commits (tokio/helix/meilisearch/helix-db). See: Examples.

Dependency Unification (unify)

Problem: We all juggle 6+ cargo plugins for dependency hygiene (hakari, udeps, machete, shear, features-manager, msrv, sort, etc.). Each runs separately, on different data, with different CLI patterns... pulling the same cargo-metadata over and over. Undeclared features (borrowed from Cargo's resolver) break isolated builds silently.

Solution: cargo rail unify — one command, one metadata call, comprehensive analysis:

cargo rail unify --check    # preview all changes
cargo rail unify            # apply workspace-wide
cargo rail unify --explain  # understand each decision

What it does:

• Unifies versions — writes to [workspace.dependencies], converts members to { workspace = true }
• Fixes undeclared features — detects features borrowed via Cargo's unified resolution
• Prunes dead features — removes features never enabled in resolved graph
• Detects unused deps — flags dependencies not used anywhere
• Computes MSRV — derives minimum Rust version from dependency graph
• Replaces workspace-hack — enable pin_transitives for cargo-hakari equivalent
• Configurable - we all have different ideas about what clean means, such as whether to remove unused dependencies or prune features or sort manifests - that's what your rail.toml file is for.

Validated impact on real repos:

Config files and validation artifacts: Examples | Validation Forks

Split + Sync (Google Copybara Replacement)

Problem: We need/want to publish crates from monorepos but want clean standalone repos with full git history. I wanted to build in a canonical dev monorepo, but release crates independently. Google'sCopybara requires so much and it's built w/ Java. Existing tools (git subtree, git-filter-repo) are one-way and manual. This offers us a bidirectional sync engine w/ 3-way merge conflict resolution in the event we need it; it never merges to main w/o a review PR for the canonical repo.

Solution: cargo rail split + cargo rail sync — bidirectional sync with 3-way conflict resolution:

# Extract crate to standalone repo with full git history
cargo rail split init crate/s  # configure once, automatically
cargo rail split run crate/s   # extract with history preserved

# Bidirectional sync
cargo rail sync crate/s --to-remote    # push monorepo changes to split repo
cargo rail sync crate/s --from-remote  # pull split repo changes (creates PR branch)

Three modes:

• single: one crate → one repo (most common)
• combined: multiple crates → one repo (shared utilities)
• workspace: multiple crates → workspace structure (mirrors monorepo)

Built on system git (not libgit2) for deterministic SHAs and full git fidelity with less attack surface/weight in the graph.

Release Automation (release)

Release checks, versioning, changelogs, tags, dependency-order publish. Release_plz is great, but it's pulling in something like 500 deps to release our work. That's too much weight to carry around in the graph and too much attack surface in my world. I release cargo-rail with 1cargo-rail.

# Cut a new release
cargo rail release run cargo-rail --bump patch --yes  # swap 'patch', 'minor', or 'major' as needed
git push origin main --follow-tags   # follow up

This gives me a clean changelog, tags, crates.io / Github release.

GitHub Actions Integration

For CICD integration, use cargo-rail-action — a thin transport over cargo rail plan -f github that handles installation, checksum verification, and output publishing for job gating. It will make output cleaner and more readable.

The action keeps CI behavior aligned with local plan + run workflows.

Config

• cargo rail init generates .config/rail.toml.
• cargo rail config sync updates .config/rail.toml with latest defaults from new releases installed.
• cargo rail config validate validates .config/rail.toml for when you're unsure.

By default, on cargo rail init, the rail.toml file is written to the .config/ directory. It's created if it doesn't exist. However, you can move/change it to the workspace root if you prefer it there. You can also 'unhide' the file if you'd like. Reference

Full documentation:

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

Migration Guides

• Migrate from cargo-hakari
• Upgrade from cargo-rail v0.9.x to v0.10.x

Tested & Proven On Large Repos

All core workflows (plan/run, unify) validated on production repos with full git history:

Validation forks: cargo-rail-testing — full configs, integration guides, and reproducible artifacts.

How to Validate:

1. Reproducibility: Every command in examples/validation-protocol.md runs on forked repos with real merge history
2. Metrics collection: Automated scripts measure execution reduction, surface accuracy, plan duration, unify impact
3. Quality audit: Heuristics flag potential false positives/negatives for human review
4. Real-world scenarios: Tests run on actual merge commits and real dependency graphs, not synthetic fixtures

Unify results (4 repos, 53 crates):

• 132 dependencies unified to [workspace.dependencies]
• 258 undeclared features fixed (silent bugs prevented)
• 2 dead features pruned
• MSRV computed for all repos (1.85.0 - 1.88.0)

Full protocol and raw artifacts: examples/README.md

Examples

Each workflow includes working config files and reproducible command sequences:

Full validation configs: Each fork in cargo-rail-testing includes:

• .config/rail.toml — production-ready config
• docs/cargo-rail-integration-guide.md — step-by-step integration
• docs/CHANGE_DETECTION_METRICS.md — measured impact analysis

Getting Help

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

License

Licensed under MIT.