{"id":34351661,"url":"https://github.com/loadingalias/cargo-rail","last_synced_at":"2026-02-14T06:18:57.550Z","repository":{"id":322954778,"uuid":"1091553183","full_name":"loadingalias/cargo-rail","owner":"loadingalias","description":"Graph-aware monorepo orchestration for Rust workspaces","archived":false,"fork":false,"pushed_at":"2026-02-11T03:18:58.000Z","size":54462,"stargazers_count":194,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-02-11T08:58:18.080Z","etag":null,"topics":["build-tools","cargo","cargo-plugin","change-detection","ci","cicd","copybara","dependency-management","developer-tools","devtools","git-subtree","hakari","monorepo","release-automation","rust","workspace","workspace-hack"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loadingalias.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-07T07:12:01.000Z","updated_at":"2026-02-11T03:19:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/loadingalias/cargo-rail","commit_stats":null,"previous_names":["loadingalias/cargo-rail"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/loadingalias/cargo-rail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loadingalias%2Fcargo-rail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loadingalias%2Fcargo-rail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loadingalias%2Fcargo-rail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loadingalias%2Fcargo-rail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loadingalias","download_url":"https://codeload.github.com/loadingalias/cargo-rail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loadingalias%2Fcargo-rail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29438641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T05:24:35.651Z","status":"ssl_error","status_checked_at":"2026-02-14T05:24:34.830Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build-tools","cargo","cargo-plugin","change-detection","ci","cicd","copybara","dependency-management","developer-tools","devtools","git-subtree","hakari","monorepo","release-automation","rust","workspace","workspace-hack"],"created_at":"2025-12-18T01:05:05.980Z","updated_at":"2026-02-14T06:18:57.545Z","avatar_url":"https://github.com/loadingalias.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cargo-rail\n\n\u003e Cargo-native control plane for Rust monorepos: plan changes, run only needed work locally and in CI, unify the graph (deps/features), split/sync crates into new repos/monorepos, and automate releases with 14 core dependencies.\n\n[![Crates.io](https://img.shields.io/crates/v/cargo-rail.svg)](https://crates.io/crates/cargo-rail) [![docs.rs](https://img.shields.io/docsrs/cargo-rail)](https://docs.rs/cargo-rail) [![CI](https://img.shields.io/github/actions/workflow/status/loadingalias/cargo-rail/commit.yaml?branch=main)](https://github.com/loadingalias/cargo-rail/actions/workflows/commit.yaml) [![MSRV](https://img.shields.io/crates/msrv/cargo-rail)](https://github.com/loadingalias/cargo-rail/blob/main/Cargo.toml)\n\n## Why cargo-rail\n\n**Impact on real repos (validated across tokio, helix, meilisearch):**\n\n| Metric | Impact |\n|---|---|\n| **CI surface execution** | 55% fewer surfaces run per merge |\n| **Weighted test/build units** | 64% reduction in compute units |\n| **Dependencies unified** | 78 across 47 crates (avg 1.7 per crate) |\n| **Undeclared features fixed** | 141 silent bugs prevented |\n| **Tooling consolidation** | 6 cargo plugins → 1 command |\n| **MSRV computation** | Automatic from dependency graph |\n\n**Two compound effects = massive time/cost savings:**\n1. **Change detection** (`plan`/`run`) reduces what runs — 55% fewer CI surfaces, 64% fewer compute units\n2. **Dependency unification** (`unify`) reduces build graph complexity — cleaner deps, smaller build units, fewer rebuilds\n\n**Before cargo-rail:** Run 6 tools separately (hakari, udeps, machete, shear, features-manager, msrv), each with different data/timing\n**After cargo-rail:** `cargo rail unify --check` in one metadata call\n\n## Quick Start\n\n```bash\n# install\ncargo install cargo-rail\n\n# generate config\ncargo rail init\n\n# deterministic planning + execution\ncargo rail plan --merge-base\ncargo rail run --merge-base --profile ci\n\n# dependency hygiene\ncargo rail unify --check\n```\n\nPre-built binaries: [GitHub Releases](https://github.com/loadingalias/cargo-rail/releases)\n\n## Core Workflows\n\n### Change Planning + Execution (`plan` / `run`)\n\n**Problem:** CI wastes resources testing unchanged code. Teams either (1) test everything on every commit, or (2) build custom scripts that drift from local behavior.\n\n**Solution:** One planner contract, used everywhere:\n\n```bash\n# Local: what would CI run if I pushed this branch?\ncargo rail plan --merge-base\n\n# CI: deterministic plan → selective execution\ncargo rail plan --merge-base -f github  # outputs: build=true, test=false, docs=true, ...\ncargo rail run --merge-base --profile ci  # runs ONLY what plan selected\n```\n\n**How repos use this:**\n1. Configure change detection rules in `.config/rail.toml` (infrastructure files, doc-only changes, etc.)\n2. Run `plan` to see impact classification (which surfaces: build, test, bench, docs, infra)\n3. Run `run` to execute only selected surfaces — locally or in CI\n4. Use `--explain` to understand any decision: \"why did this run?\" / \"why was this skipped?\"\n\nResult: **55% fewer CI surface executions, 64% reduction in weighted compute units** (validated on tokio/helix/meilisearch).\n\n### Dependency Unification (`unify`)\n\n**Problem:** Teams juggle 6+ cargo plugins for dependency hygiene (hakari, udeps, machete, shear, features-manager, msrv). Each runs separately, on different data, with different CLI patterns. Undeclared features (borrowed from Cargo's resolver) break isolated builds.\n\n**Solution:** `cargo rail unify` — one command, one metadata call, comprehensive analysis:\n\n```bash\ncargo rail unify --check    # preview all changes\ncargo rail unify            # apply workspace-wide\ncargo rail unify --explain  # understand each decision\n```\n\n**What it does:**\n- **Unifies versions** — writes to `[workspace.dependencies]`, converts members to `{ workspace = true }`\n- **Fixes undeclared features** — detects features borrowed via Cargo's unified resolution\n- **Prunes dead features** — removes features never enabled in resolved graph\n- **Detects unused deps** — flags dependencies not used anywhere\n- **Computes MSRV** — derives minimum Rust version from dependency graph\n- **Replaces workspace-hack** — enable `pin_transitives` for cargo-hakari equivalent\n\n**Validated impact on real repos:**\n\n| Repository | Crates | Locked Deps | Deps Unified | Undeclared Features | MSRV Computed |\n|---|---:|---:|---:|---:|---|\n| tokio-rs/tokio | 10 | 224 | 9 | 19 | 1.85.0 |\n| helix-editor/helix | 14 | 351 | 15 | 25 | 1.87.0 |\n| meilisearch/meilisearch | 23 | 835 | 54 | 97 | 1.88.0 |\n| **Aggregate** | **47** | **1,410** | **78** | **141** | — |\n\nConfig files and validation artifacts: [examples/unify/](examples/unify/)\n\n**Tools replaced:** cargo-hakari, cargo-udeps, cargo-machete, cargo-shear, cargo-features-manager, cargo-msrv (6 tools → 1 command)\n\n### Split + Sync (Google Copybara Replacement)\n\n**Problem:** Teams need to publish crates from monorepos but want clean standalone repos with full git history. Existing tools (git subtree, git-filter-repo) are one-way and manual. Google's Copybara requires Bazel and complex config.\n\n**Solution:** `cargo rail split` + `cargo rail sync` — bidirectional sync with 3-way conflict resolution:\n\n```bash\n# Extract crate to standalone repo with full git history\ncargo rail split init my-crate  # configure once\ncargo rail split run my-crate   # extract with history preserved\n\n# Bidirectional sync\ncargo rail sync my-crate --to-remote    # push monorepo changes to split repo\ncargo rail sync my-crate --from-remote  # pull split repo changes (creates PR branch)\n```\n\n**Three modes:**\n- `single`: one crate → one repo (most common)\n- `combined`: multiple crates → one repo (shared utilities)\n- `workspace`: multiple crates → workspace structure (mirrors monorepo)\n\nBuilt on system git (not libgit2) for deterministic SHAs and full git fidelity.\n\n### Release Automation (`release`)\n\nRelease checks, versioning, changelogs, tags, dependency-order publish.\n\n## Why This Model\n\n- One planner contract for local and CI.\n- One executor (`run`) for planner-selected surfaces.\n- One config (`rail.toml`) for policy.\n- Check-mode exit code `1` means \"changes detected\" (not a crash).\n\n## GitHub Actions Integration\n\nFor CI integration, use [cargo-rail-action](https://github.com/loadingalias/cargo-rail-action) — a thin transport over `cargo rail plan -f github` that handles installation, checksum verification, and output publishing for job gating.\n\nThe action keeps CI behavior aligned with local `plan` + `run` workflows.\n\n## Configuration\n\n`cargo rail init` generates `.config/rail.toml`.\n\n**Example config:**\n\n```toml\n# Platform targets for multi-target validation\ntargets = [\n  \"aarch64-apple-darwin\",\n  \"aarch64-unknown-linux-gnu\",\n  \"x86_64-pc-windows-msvc\",\n  \"x86_64-unknown-linux-gnu\",\n]\n\n[unify]\npin_transitives = false      # Enable for cargo-hakari replacement\ndetect_unused = true         # Detect unused dependencies\nprune_dead_features = true   # Remove features never enabled\nmsrv = true                  # Compute workspace rust-version\ndetect_undeclared_features = true  # Find borrowed features\n\n[release]\ntag_format = \"{prefix}{version}\"\npublish_delay = 5\nsign_tags = true\n\n[change-detection]\n# Files triggering full workspace rebuild\ninfrastructure = [\n  \".github/**\",\n  \"scripts/**\",\n  \"justfile\",\n  \"rust-toolchain.toml\",\n]\n```\n\n**Full documentation:**\n- [Configuration reference](docs/config.md)\n- [Command reference](docs/commands.md)\n- [Architecture](docs/architecture.md)\n- [Change detection recipe](docs/change-detection-recipe.md)\n- [Change detection operations guide](docs/change-detection-operations.md)\n- [Troubleshooting](docs/troubleshooting.md)\n\n## Migration Guides\n\n- Replace `affected` / `test` flows for pre-v0.10.0 releases of `cargo-rail`: [docs/adr/0001-migrate-affected-test-to-plan-run.md](docs/adr/0001-migrate-affected-test-to-plan-run.md)\n- Replace `cargo-hakari`: [docs/migrate-hakari.md](docs/migrate-hakari.md)\n\n## Proven On Large Repos\n\nAll core workflows (`plan`/`run`, `unify`, `split`, `sync`, `release`) validated on production repos:\n\n| Repository | Crates | Locked Deps | Validation Coverage |\n|---|---:|---:|---|\n| [tokio-rs/tokio](https://github.com/tokio-rs/tokio) | 10 | 224 | Plan/run (5 merges), unify, split, sync, release |\n| [helix-editor/helix](https://github.com/helix-editor/helix) | 14 | 351 | Plan/run (5 merges), unify, split, sync, release |\n| [meilisearch/meilisearch](https://github.com/meilisearch/meilisearch) | 23 | 835 | Plan/run (5 merges), unify, split, sync, release |\n\n**Why this matters:**\n\nValidation isn't a single test — it's a protocol:\n\n1. **Reproducibility**: Every command in [docs/large-repo-validation.md](docs/large-repo-validation.md) runs on forked repos with real merge history\n2. **Metrics collection**: Automated scripts measure execution reduction, surface accuracy, plan duration, unify impact\n3. **Quality audit**: Heuristics flag potential false positives/negatives for human review\n4. **Real-world scenarios**: Tests run on actual merge commits and real dependency graphs, not synthetic fixtures\n\n**Change detection results (15 merge scenarios):**\n- 55% execution reduction rate (surfaces)\n- 64% weighted reduction rate (compute units)\n- Average plan duration: 632ms\n- Quality audit: 2 potential false-negatives, 1 potential false-positive (flagged for review)\n\n**Unify results (3 repos, 47 crates):**\n- 78 dependencies unified\n- 141 undeclared features fixed (silent bugs prevented)\n- 2 dead features pruned\n- MSRV computed for all repos (1.85.0 - 1.88.0)\n\nFull protocol and raw artifacts: [examples/README.md](examples/README.md)\n\n## Examples\n\nEach workflow includes working config files and reproducible command sequences:\n\n- Change detection: [examples/change_detection/](examples/change_detection/)\n- Unify: [examples/unify/](examples/unify/)\n- Split/sync: [examples/split-sync/](examples/split-sync/)\n- Release: [examples/release/](examples/release/)\n\nAll examples run on real repos (tokio, helix, meilisearch) and include:\n- Rail config (`.config/rail.toml`)\n- Command sequence (step-by-step)\n- Expected outputs\n- Validation artifacts\n\n## Getting Help\n\n- Issues: [GitHub Issues](https://github.com/loadingalias/cargo-rail/issues)\n- Crate: [crates.io/cargo-rail](https://crates.io/crates/cargo-rail)\n\n## License\n\nLicensed under [MIT](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floadingalias%2Fcargo-rail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floadingalias%2Fcargo-rail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floadingalias%2Fcargo-rail/lists"}