cargo-rail: feat(unify): add sync subcommand to re-detect and sync targets

  - Adds 'cargo rail unify sync' command
  - Scans workspace for target triples and replaces rail.toml targets
  - Excludes all rail.toml locations from detection (avoids circular detection)
  - Preserves all other config (comments, unify settings, release settings)
  - Includes --check mode for preview
  - Updates README with improved docs and CI/CD workflow examples
  - Adds cargo-binstall metadata for pre-built binary downloads
  - Adds 7 integration tests

Author: loadingalias

Cargo.toml

@@ -7,7 +7,6 @@ license = "MIT"
 authors = ["loadingalias"]
 description = "Graph-aware testing, dependency unification, and crate extraction for Rust monorepos"
 repository = "https://github.com/loadingalias/cargo-rail"
-homepage = "https://loadingalias.github.io/cargo-rail"
 documentation = "https://docs.rs/cargo-rail"
 categories = [
     "development-tools::cargo-plugins",
@@ -39,3 +38,18 @@ tempfile = "3.23.0"
 [[test]]
 name = "integration"
 path = "tests/integration/mod.rs"
+
+# cargo-binstall metadata for pre-built binary downloads
+# See: https://github.com/cargo-bins/cargo-binstall
+[package.metadata.binstall]
+pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }.tar.gz"
+pkg-fmt = "tgz"
+
+# Windows uses .zip instead of .tar.gz
+[package.metadata.binstall.overrides.x86_64-pc-windows-msvc]
+pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }.zip"
+pkg-fmt = "zip"
+
+[package.metadata.binstall.overrides.aarch64-pc-windows-msvc]
+pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }.zip"
+pkg-fmt = "zip"

README.md

@@ -6,24 +6,23 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Rust 1.91+](https://img.shields.io/badge/rust-1.91%2B-orange.svg)](https://www.rust-lang.org)
 
-[Commands](docs/commands.md) · [Config](docs/config.md) · [Examples](examples/) · [Crates.io](https://crates.io/crates/cargo-rail)
+[Command Reference](docs/commands.md) · [Config Reference](docs/config.md) · [Demo Videos](examples/)
 
 ```bash
 cargo install cargo-rail
 ```
 
-Pre-built binaries available on the [Releases page](https://github.com/loadingalias/cargo-rail/releases).
+Pre-built binaries available on the [Releases Page](https://github.com/loadingalias/cargo-rail/releases).
 
 ---
 
 ## TLDR
 
 - **Only test what changed both locally and in CI**: `cargo rail test`
-- **Keep manifests clean and unified**: `cargo rail unify`
+- **Keep manifests clean and unified**: `cargo rail unify` / `cargo rail unify sync`
 - **Split + sync crates with full git history**: `cargo rail split` / `cargo rail sync`
 - **Release in dependency order with changelogs**: `cargo rail release`
-
-Pure dev tooling. No workspace-hack crate. 11 direct dependencies.
+- **Minimal deps**: 11 core dependencies; 77 resolved dependencies
 
 ---
 
@@ -33,54 +32,66 @@ Drop into any Rust workspace:
 
 ```bash
 cargo install cargo-rail
-cargo rail unify --check
-cargo rail unify --backup
-cargo rail test
-```
-
-Optional configuration (auto-detected location):
-
-```bash
-cargo rail init                 # Generates .config/rail.toml by default
-cargo rail config validate      # Sanity-check config
+cargo rail init                               # Initialize once
+cargo rail config validate                    # Validate config
+cargo rail unify --check                      # Dry-run 'unify'
+cargo rail unify                              # Initial 'unify' automatically writes backup
+cargo rail test                               # Auto-detect Nextest; native change-detection
 ```
 
-See [docs/commands.md](docs/commands.md)
+See [docs/commands.md](docs/commands.md) for details.
 
 ---
 
 ## Workflows
 
 ### Change Detection & Testing
 
-Only run tests for crates affected by your changes, with nextest auto-detection:
+Graph-aware change detection. Only check/test/bench what's affected:
+
+```bash
+cargo rail affected                           # Show affected crates
+cargo rail affected -f names-only             # Just names (for scripting)
+cargo rail test                               # Run tests for affected crates
+cargo rail test --all                         # Override and run the whole workspace
+```
+
+Wire it into your local workflow:
 
 ```bash
-cargo rail affected              # Show affected crates
-cargo rail test                  # Run tests for affected crates
-cargo rail test --all            # Override and run the whole workspace
+# scripts/check.sh (or justfile)
+AFFECTED=$(cargo rail affected -f names-only 2>/dev/null || echo "")
+if [ -z "$AFFECTED" ]; then
+  cargo check --workspace --all-targets
+else
+  for crate in $AFFECTED; do FLAGS="$FLAGS -p $crate"; done
+  cargo check $FLAGS --all-targets
+fi
 ```
 
 For CI, see [`cargo-rail-action`](https://github.com/loadingalias/cargo-rail-action).
 
 ### Dependency Unification
 
-Resolution-based `[workspace.dependencies]` management using Cargo’s resolver:
+Resolution-based `[workspace.dependencies]` management using Cargo's resolver:
 
 ```bash
-cargo rail unify --check         # Preview changes (CI-safe)
+cargo rail unify --check         # Preview changes (CI-safe, exits 1 if changes needed)
 cargo rail unify                 # Apply changes
-cargo rail unify --backup        # Apply with manifest backups; backup is automatic on the first 'unify' run
-cargo rail unify undo            # Restore from a previous backup; default last
+cargo rail unify --backup        # Apply with manifest backups
+cargo rail unify undo            # Restore from a previous backup
+cargo rail unify sync            # Re-detect targets and merge into rail.toml
 ```
 
 What it does, per target triple (`targets` in `rail.toml`):
 
 - **Unifies versions** based on what Cargo actually resolved
-- **Computes MSRV** from the resolved graph (`[workspace.package].rust-version`)
+- **Computes MSRV (dependencies)** from the resolved graph (`[workspace.package].rust-version`)
 - **Prunes dead features** that are never enabled
 - **Detects/removes unused deps** (opt-in via config)
-- **Optionally pins transitives** (workspace-hack replacement)
+- **Optionally pins transitives** (`cargo-hakari` or workspace-hack replacement)
+
+Use `unify sync` in pre-commit hooks or CI to enforce a lean, consistent dependency graph or after adding new target triples to your CI matrix or `.cargo/config.toml`.
 
 ### Split & Sync
 
@@ -89,81 +100,81 @@ Extract crates to standalone repos and keep them in sync, with deterministic SHA
 Three modes: single crate to new repo, multiple crates to new repo, or multiple crates to a new workspace.
 
 ```bash
-cargo rail split init crate              # Configure split for crate/s
-cargo rail split run crate --check        # Preview the split
-cargo rail split run crate               # Execute the split
+cargo rail split init crate                   # Configure split for crate/s
+cargo rail split run crate --check            # Preview the split
+cargo rail split run crate                    # Execute the split
 
-cargo rail sync crate                    # Bidirectional sync
-cargo rail sync crate --to-remote         # Monorepo -> split repo
-cargo rail sync crate --from-remote       # Split repo -> monorepo (PR branch)
+cargo rail sync crate                         # Bidirectional sync
+cargo rail sync crate --to-remote             # Monorepo -> split repo
+cargo rail sync crate --from-remote           # Split repo -> monorepo (PR branch)
 ```
 
-Split/sync behavior is driven by `[crates.NAME.split]` in `rail.toml`. See [docs/config.md](docs/config.md)
+Split/sync behavior is driven by `[crates.NAME.split]` in `rail.toml`. 3-way conflict resolution is configurable in `rail.toml` once a split has been initialized. See [docs/config.md](docs/config.md)
 
 ### Release
 
 Version bumping, changelog generation, tagging, and publishing in dependency order:
 
 ```bash
-cargo rail release init crate                    # Configure release
-cargo rail release check crate                   # Fast validation
-cargo rail release check crate --extended        # Dry-run + MSRV check
-cargo rail release run crate --check             # Preview release plan
-cargo rail release run crate --bump minor        # Execute release
+cargo rail release init crate                 # Configure release
+cargo rail release check crate                # Fast validation
+cargo rail release check crate --extended     # Dry-run + MSRV check
+cargo rail release run crate --check          # Preview release plan
+cargo rail release run crate --bump minor     # Execute release
 ```
 
 Configure once in `rail.toml`:
 
 ```toml
 [release]
 tag_prefix = "v"
-tag_format = "{crate}-{prefix}{version}"         # Adjust for standalone crate
+tag_format = "{crate}-{prefix}{version}"      # Adjust for standalone crate
 require_clean = true
 ```
 
 ---
 
-## Example Videos
+## Demo Videos
 
-Real workspaces, recorded command workflows end-to-end. All assets live under [`examples/`](examples/).
+I've tested across trusted Rust workspaces and recorded the command workflows end-to-end. All assets live under [`examples/`](examples/).
 
 <details>
-<summary><strong>Unify: ripgrep</strong> - baseline unification in a widely trusted workspace</summary>
+<summary><strong>ripgrep</strong> - baseline unification in a widely trusted workspace</summary>
 
 https://github.com/user-attachments/assets/93f34633-aa0e-4cde-8723-c81f3f474bac
 
 </details>
 
 <details>
-<summary><strong>Unify: tokio</strong> - conservative settings for a core ecosystem library</summary>
+<summary><strong>tokio</strong> - conservative settings for a core ecosystem library</summary>
 
 https://github.com/user-attachments/assets/520abf55-cf45-43af-8dc8-0eed0a58ce72
 
 </details>
 
 <details>
-<summary><strong>Unify: polars</strong> - large workspace with <code>pin_transitives</code> (cargo-hakari replacement)</summary>
+<summary><strong>polars</strong> - large workspace with <code>pin_transitives</code> (cargo-hakari replacement)</summary>
 
 https://github.com/user-attachments/assets/31bf5ff5-7185-4e59-acaa-ea8edd3c6f48
 
 </details>
 
 <details>
-<summary><strong>Unify: helix-db</strong> - unification on a growing project</summary>
+<summary><strong>helix-db</strong> - unification on a growing project</summary>
 
 https://github.com/user-attachments/assets/3520d254-e69c-460c-b894-eb126b42a1ea
 
 </details>
 
 <details>
-<summary><strong>Split: ruff</strong> - extracting crates with full git history</summary>
+<summary><strong>ruff</strong> - extracting crates with full git history</summary>
 
 https://github.com/user-attachments/assets/b9f56e77-de0a-42c1-b2ef-1a40bb24f5ac
 
 </details>
 
 <details>
-<summary><strong>Release: tikv</strong> - version bumping, changelog, and publishing in dependency order</summary>
+<summary><strong>tikv</strong> - version bumping, changelog, release, and publishing in dep order</summary>
 
 https://github.com/user-attachments/assets/9c0b6df1-8539-44a0-9c82-a9fdca5e075c
 
@@ -173,9 +184,9 @@ https://github.com/user-attachments/assets/9c0b6df1-8539-44a0-9c82-a9fdca5e075c
 
 ## Unification Results in Testing/Validation
 
-`cargo rail unify` on trusted Rust monorepos:
+`cargo rail unify` on a few different projects:
 
-| Repository | Crates | Deps Unified | Member Edits |
+| Repo | Crates | Deps Unified | Member Edits |
 |------------|--------|--------------|--------------|
 | [tikv](https://github.com/tikv/tikv) | 83 | 57 | 519 |
 | [polars](https://github.com/pola-rs/polars) | 33 | 2 | 13 |
@@ -185,43 +196,47 @@ https://github.com/user-attachments/assets/9c0b6df1-8539-44a0-9c82-a9fdca5e075c
 | [ripgrep](https://github.com/BurntSushi/ripgrep) | 10 | 9 | 41 |
 | [helix-db](https://github.com/helixdb/helix-db) | 6 | 16 | 44 |
 
-Full demos and reports live under [`examples/`](examples/).
+Full demos and reports live under [`examples/`](examples/) for most examples.
 
 ---
 
-## Could Replace
+### Potentially Replaces
 
 | Tool | cargo-rail equivalent |
 |------|-----------------------|
-| cargo-hakari | `unify` with `pin_transitives = true` |
-| cargo-udeps, cargo-machete, cargo-shear | `unify` with `detect_unused = true` / `remove_unused = true` |
-| cargo-msrv (for dep-driven MSRV) | `unify` with `msrv = true` |
-| cargo-release, release-plz | `release` command |
-| git-cliff | Built-in changelog generation |
-| Google's Copybara for Rust teams | `split` + `sync` commands |
+| `cargo-hakari` | `unify` with `pin_transitives = true` |
+| `cargo-udeps` / `cargo-machete` / `cargo-shear` | `unify` with `detect_unused = true` / `remove_unused = true` |
+| `cargo-msrv` (for dep-driven MSRV)* | `unify` with `msrv = true` |
+| `cargo-release` / `release-plz` | `release` command |
+| `git-cliff` | Built-in changelog generation |
+| Google's `Copybara` for Rust teams | `split` + `sync` commands |
 | Mountain of shell scripts | `test` + `affected` + [`cargo-rail-action`](https://github.com/loadingalias/cargo-rail-action) in CI |
 
+#### NOTE ON MSRV
+
+The `msrv=true` configuration doesn't mean `cargo-rail` runs compilation checks. Instead, it computes the floor msrv for the workspace, and takes your own `rust-version` into consideration. This allows you to immediately determine the msrv for your workspace based on the dependencies you're using and your own `rust-version`.
+
 ---
 
 ## Design Notes
 
-I've built cargo-rail as a necessity for my own work. I've explained the reasoning behind it and touched on the plans for the future in this post: [Rust Monorepo Tooling](http://loadingalias.com/blog). I would love contributions; I'd love to iron out the details and workflows that we all use daily but that are clunky.
+I've built cargo-rail as a necessity for my own work and for that reason it's opinionated. I've explained the thought process behind it and touched on the plans for the future in this post: [Coming Soon](http://loadingalias.com/blog/). I am absolutely hoping to get the community involved in improving the tooling here; contributions are welcome!
 
 **Supply-Chain Safety**
 
-This matters a great deal to me. I've tried to keep the tool itself lean; avoids large meta-dependency graphs. Currently, cargo-rail depends on 11 core deps; 77 resolved in the release build.
+This matters a great deal to me. I've tried to keep the tool itself lean; it deliberately avoids large meta-dependency graphs. Currently, cargo-rail depends on 11 core deps; 77 resolved in the release build.
 
 **Multi-Target Resolution**
 
-Runs `cargo metadata --filter-platform` per target and computes feature intersection, not union. I often build for 7-9 target-triples; this was a requirement.
+cargo-rail runs `cargo metadata --filter-platform` per target-triple and computes feature intersection, not union... with guardrails in place, obviously. I often build for 6-9 target-triples... so this was a requirement.
 
 **System Git > Gix**
 
-I've used the `git` binary directly for deterministic SHAs and proper history, no libgit2/gitoxide. They felt a bit heavy for the use case and we all use Git locally in some fashion.
+I've used the `git` binary directly for deterministic SHAs and proper history, no `libgit2` / `gitoxide`. They felt a bit heavy for this use case and I'm assuming we all use git locally in some fashion anyway.
 
 **Lossless TOML**
 
-Uses `toml_edit` so existing comments and layout are preserved. Manipulating TOML is honestly not as easy as it sounds. Please, if you run into any problems... open an 'Issue' and I'll take a look.
+I've used `toml_edit` so that existing comments and layout are preserved. Manipulating TOML is not as straightforward as it sounds. Please, if you run into any problems... open an 'Issue' and I'll take a look... or submit a PR.
 
 **Contributions Welcome**
 

docs/commands.md

@@ -150,18 +150,19 @@ Usage: cargo rail unify [OPTIONS] [COMMAND]
 
 Commands:
   undo  Restore manifests from a previous backup
+  sync  Re-detect and sync targets to rail.toml
   help  Print this message or the help of the given subcommand(s)
 
 Options:
   -q, --quiet
           Suppress progress messages (for CI/automation)
 
-  -c, --check
-          Dry-run mode: preview changes without modifying files
-
       --json
           Output in JSON format (shorthand for -f json)
 
+  -c, --check
+          Dry-run mode: preview changes without modifying files
+
   -f, --format <FORMAT>
           Output format
 
@@ -200,6 +201,8 @@ Examples:
   cargo rail unify --show-diff            # Show manifest changes
   cargo rail unify undo                   # Restore from backup
   cargo rail unify undo --list            # List available backups
+  cargo rail unify sync --check           # Preview target sync
+  cargo rail unify sync                   # Re-detect and merge targets into rail.toml
 ```
 
 ---
@@ -222,6 +225,34 @@ Options:
 
 ---
 
+### cargo rail unify sync
+
+```
+Re-detect and sync targets to rail.toml
+
+Scans workspace for target triples (rust-toolchain.toml, .cargo/config.toml, etc.) and merges any new targets into your rail.toml configuration. Preserves existing targets and all other settings.
+
+Usage: cargo rail unify sync [OPTIONS]
+
+Options:
+  -c, --check
+          Preview changes without modifying rail.toml
+
+  -q, --quiet
+          Suppress progress messages (for CI/automation)
+
+      --json
+          Output in JSON format (shorthand for -f json)
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+  -V, --version
+          Print version
+```
+
+---
+
 ## cargo rail init
 
 ```