cargo-rail is a CLI-first monorepo tool for Rust development. The architecture is simple on purpose.
Build WorkspaceContext once and pass it by reference everywhere else.
That context owns:
- git state
- cargo metadata state (resolved)
- workspace dependency graph
- loaded config
Commands do not reload metadata independently.
| Layer | Purpose |
|---|---|
commands/ |
CLI handlers and command dispatch |
workspace/ |
WorkspaceContext construction and shared state |
graph/ |
dependency graph queries |
cargo/ |
metadata, manifests, unify logic |
git/ |
system git integration |
change_detection/ |
file classification and planner taxonomy |
release/ |
release planning and publishing |
split/ / sync/ |
repository extraction and bidirectional sync |
toml/ |
lossless manifest editing |
- Parse CLI
- Initialize output mode
- Handle early commands that do not need full context
- Build
WorkspaceContext - Dispatch the selected command
cargo rail plan follows a fixed path:
- collect changed files
- classify file kinds and custom surfaces
- resolve file ownership
- compute graph impact
- emit trace and surface decisions
- project execution scope
impact is diagnostic. scope is the execution handoff.
cargo rail unify:
- loads cargo metadata
- analyzes resolved dependencies
- computes a mutation plan
- applies lossless TOML edits
- system git instead of libgit2
- petgraph directly instead of another abstraction layer
- lossless TOML editing so manifests keep comments and formatting
- thin
main.rs, with logic in the library crate
| Change | File or module |
|---|---|
| CLI shape | src/commands/cli.rs |
| command dispatch | src/commands/mod.rs |
| context loading | src/workspace/context.rs |
| planner behavior | src/commands/plan.rs |
| graph algorithms | src/graph/ |
| unify behavior | src/cargo/ |
| config parsing | src/config/ |