cargo-rail

Graph-aware monorepo orchestration for Rust workspaces.

What It Replaces

cargo-hakari

cargo rail unify

cargo-udeps

cargo-machete

cargo-shear

cargo rail unify

cargo-features-manager

cargo rail unify

cargo-msrv

cargo rail unify

paths-filter

cargo rail affected

git subtree

git-filter-repo

cargo rail split

release-plz

cargo-release

git-cliff

cargo rail release

11 dependencies. One config file.

MSRV policy

• MSRV source of truth:

  Cargo.toml

  (

  rust-version

  , written as

  major.minor.patch

  )
• Cargo requirement: Cargo shipped with that Rust release (newer Cargo is fine)
• CI: builds on MSRV to prevent accidental bumps
• Workspaces:

  cargo rail unify

  writes

  [workspace.package].rust-version

  ; enable

  [unify].enforce_msrv_inheritance = true

  to set

  [package].rust-version = { workspace = true }

  in member crates

Quick Start

cargo rail init              # generate .config/rail.toml
cargo rail unify --check     # preview what would change (read-only)
cargo rail unify             # apply changes

Commands

affected

/

test

Graph-aware change detection. Only test what's affected:

cargo rail affected                    # list affected crates
cargo rail affected --merge-base       # compare against merge-base (CI)
cargo rail affected -f cargo-args      # output: -p crate1 -p crate2
cargo rail affected -f github-matrix   # output: JSON matrix for Actions
cargo rail test                        # run tests for affected crates
cargo rail test --explain              # show why each crate is affected

CI Integration:

- uses: loadingalias/cargo-rail-action@v1
  id: rail

- run: cargo nextest run ${{ steps.rail.outputs.cargo-args }}
  if: steps.rail.outputs.should-test == 'true'

unify

Dependency unification based on Cargo's resolved output:

cargo rail unify --check    # preview changes (exits 1 if drift detected)
cargo rail unify            # apply to workspace
cargo rail unify --explain  # show reasoning for each change
cargo rail unify undo       # restore from backup

What it does:

• Unifies versions — writes to

  [workspace.dependencies]

  , converts members to

  workspace = true

• Prunes dead features — removes features never enabled in the resolved graph
• Fixes undeclared features — adds missing feature declarations to member manifests
• Detects unused deps — flags dependencies not used anywhere (auto-removes on apply)
• Computes MSRV — derives minimum Rust version from dependency graph
• Pins transitives — replaces

  cargo-hakari

  without a workspace-hack crate

Multi-target aware: runs

cargo metadata

split

/

sync

Extract crates with full git history. Bidirectional sync with 3-way conflict resolution:

cargo rail split init crate/s         # configure extraction
cargo rail split run crate/s          # extract with history
cargo rail split run crate/s --check  # preview (dry-run)

cargo rail sync crate/s               # bidirectional sync
cargo rail sync crate/s --to-remote   # push changes to split repo
cargo rail sync crate/s --from-remote # pull 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)

Safety: refuses dirty worktree by default.

--allow-dirty

--yes

release

Dependency-order publishing with changelog generation:

cargo rail release check crate/s              # validate release readiness
cargo rail release run crate/s --bump minor   # bump, tag, publish
cargo rail release run crate/s --check        # preview release plan

Safety: detects default branch, refuses detached HEAD, warns on non-default branch.

config

Manage configuration:

cargo rail init              # generate .config/rail.toml
cargo rail config locate     # print active config path
cargo rail config print      # print effective config with defaults
cargo rail config validate   # check for errors and unknown keys
cargo rail config sync       # update config with detected targets (incredibly useful on update)

Configuration

Generated by

cargo rail init

.config/rail.toml

targets = ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin"]

[unify]
pin_transitives = false      # enable for hakari replacement
detect_unused = true
prune_dead_features = true

msrv = true
msrv_source = "max"          # deps | workspace | max
enforce_msrv_inheritance = false

[release]
tag_format = "{crate}-{prefix}{version}"
publish_delay = 5            # seconds between publishes

[change-detection]
infrastructure = [".github/**", "scripts/**", "*.sh"]

See full reference.

Notes

• vs cargo-hakari: No workspace-hack crate. Writes directly to

  [workspace.dependencies]

  . Use

  pin_transitives = true

  for equivalent behavior.
• Workspace inheritance: Yes. Converts members to

  { workspace = true }

  .
• Virtual workspaces: Supported. Auto-selects transitive host or configure explicitly.
• Private registries: Works via

  cargo metadata

  , respects

  .cargo/config.toml

  .
• Undeclared features: Detects when crates "borrow" features from siblings (works in workspace, breaks on publish). Auto-fixes by adding missing declarations.

References

• Config Reference
• Migration Guide