cargo-rail: fixing conditional compilation feature flag pruning; updating cmd/cfg in readme

Author: loadingalias

README.md

@@ -1,6 +1,6 @@
 # cargo-rail
 
-**Graph-aware monorepo orchestration for Rust workspaces.**
+**Monorepo orchestration for Rust workspaces.**
 
 [![Crates.io](https://img.shields.io/crates/v/cargo-rail.svg)](https://crates.io/crates/cargo-rail)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -14,174 +14,50 @@ cargo install cargo-rail
 
 ---
 
-## The Problem
-
-Rust monorepos are powerful but painful:
-
-- **CI tests everything** on every PR. 50 crates, 12 minutes, every time.
-- **Dependency fragmentation** causes duplicate compilations. You're maintaining a workspace-hack crate or living with the overhead.
-- **Extracting crates** means git-filter-repo scripts, lost commit mappings, and manual coordination.
-- **Releasing** requires juggling cargo-release, git-cliff, and custom scripts.
-
-**cargo-rail** solves all of these with one tool and 12 dependencies.
-
----
-
 ## What It Does
 
-### Test only what changed
+**Test only what changed** — Graph-aware change detection. Auto-detects nextest. 70-90% CI reduction.
 
 ```bash
-$ cargo rail test
-
-Changed: crates/core/src/lib.rs
-
-Affected crates:
-  core        (direct change)
-  api         (depends on core)
-  cli         (depends on api)
-
-Skipped (no dependency path):
-  examples
-  benchmarks
-
-Running: cargo nextest run -p core -p api -p cli
+cargo rail test
 ```
 
-Graph-aware change detection. Auto-detects nextest. **70-90% reduction in CI time.**
-
-### Unify dependencies without workspace-hack
+**Unify dependencies** — Resolution-based `[workspace.dependencies]` without workspace-hack crates.
 
 ```bash
-$ cargo rail unify
-
-Analyzed 3 target triples
-Unified 23 dependencies to [workspace.dependencies]
-Pinned 8 transitive-only deps
-Computed MSRV: 1.75.0
-
-Features: minimal set for full functionality
-Versions: resolved from Cargo's actual resolver
-TOML: comments and formatting preserved
+cargo rail unify --check    # Preview
+cargo rail unify            # Apply
 ```
 
-- **Multi-target resolution** — Analyzes all your target triples, produces one correct dependency graph
-- **Minimum features** — Intersection of required features, not union. Leaner builds.
-- **Prune dead features** — Removes features declared but never used (`prune_dead_features = true`)
-- **Detect & remove unused deps** — Finds deps declared but not in the resolved graph (`detect_unused = true`, `remove_unused = true`)
-- **Automatic MSRV** — Computes workspace MSRV from dependency requirements (`msrv = true`)
-- **No workspace-hack crate** — Native `[workspace.dependencies]`, nothing extra
-
-### Split crates with full git history
+**Split crates with history** — Extract crates to standalone repos. Deterministic SHAs, git-notes mapping.
 
 ```bash
-$ cargo rail split run my-crate
-
-Extracted my-crate to standalone repo
-  347 commits preserved
-  Same commit SHAs (deterministic)
-  Commit mapping stored in git-notes
+cargo rail split run my-crate
 ```
 
-Three modes:
-
-| Mode | Use Case |
-|------|----------|
-| `single` | One crate → one repo |
-| `multi` | Multiple crates → one repo (separate directories) |
-| `workspace` | Multiple crates → one monorepo (with workspace Cargo.toml) |
-
-### Sync with safe defaults
+**Sync bidirectionally** — Monorepo ↔ split repo. Changes from external repos create PR branches.
 
 ```bash
-$ cargo rail sync my-crate
-
-Monorepo → split: pushes to main
-Split → monorepo: creates PR branch (never direct to main)
+cargo rail sync my-crate
 ```
 
-Bidirectional sync with safety guardrails. Changes from external contributors come in as PRs for review.
-
-### Release with dependency ordering
+**Release with ordering** — Dependency-ordered publishing. Native changelog generation.
 
 ```bash
-$ cargo rail release run --all --bump minor --check
-
-Planning release:
-  1. core       0.4.2 → 0.5.0
-  2. api        0.3.1 → 0.4.0  (depends on core)
-  3. cli        0.2.0 → 0.3.0  (depends on api)
-
-Changelog generated from conventional commits
-Tags: [email protected], [email protected], [email protected]
-
-Run without --check to apply.
+cargo rail release run --all --bump minor --check
 ```
 
-Native changelog generation. Configurable publish delays. GitHub releases via `gh`.
-
----
-
-## Real-World Impact
-
-`cargo rail affected` on recent commits (HEAD~10):
-
-| Repository | Crates | Affected | Skipped | Reduction |
-|------------|--------|----------|---------|-----------|
-| [helix](https://github.com/helix-editor/helix) | 13 | 5 | 8 | 62% |
-| [ripgrep](https://github.com/BurntSushi/ripgrep) | 10 | 4 | 6 | 60% |
-| [vello](https://github.com/linebender/vello) | 26 | 13 | 13 | 50% |
-| [tikv](https://github.com/tikv/tikv) | 83 | 42 | 41 | 49% |
-| [ruff](https://github.com/astral-sh/ruff) | 43 | 23 | 20 | 47% |
-| [meilisearch](https://github.com/meilisearch/meilisearch) | 19 | 17 | 2 | 11% |
-| [polars](https://github.com/pola-rs/polars) | 33 | 32 | 1 | 3% |
-
-*Results vary by commit range. Monorepos with focused PRs see larger reductions.*
-
 ---
 
 ## Why cargo-rail
 
-### 12 dependencies, 98 resolved
-
-Compare: cargo-hakari pulls ~40 direct via guppy. release-plz pulls 600+ resolved.
-
-Minimal supply chain. Easy to audit. Fast to compile.
-
-### Correct by construction
-
-cargo-rail queries Cargo's actual resolver across all your target triples:
-
-```toml
-# crate-a: tokio = "1.0"          (needs rt)
-# crate-b: tokio = "^1.5"         (needs net)
-# crate-c: tokio = "1"            (needs sync, linux-only)
-
-# cargo-rail resolves across x86_64-linux, aarch64-darwin, x86_64-windows:
-[workspace.dependencies]
-tokio = { version = "1.5", features = ["rt", "net", "sync"] }
-```
-
-- **Versions**: Always the resolved version, not the requested range
-- **Features**: Minimum set required across all targets (intersection, not union)
-- **MSRV**: Auto-computed from dependency requirements when `msrv = true`
-
-### System git, no libgit2
-
-Split and sync use the system `git` binary directly. No libgit2 or gitoxide dependencies:
+**11 dependencies, ~100 resolved.** Compare: cargo-hakari pulls ~40 direct via guppy. release-plz pulls 600+ resolved.
 
-- Maximum fidelity with your existing git workflows
-- Deterministic: same input → same commit SHAs
-- git-notes for rebase-safe commit mapping
+**Multi-target resolution.** Queries Cargo's actual resolver across all your target triples. Computes intersection of required features (not union).
 
-### Lossless TOML editing
+**System git.** Uses `git` binary directly. No libgit2/gitoxide. Deterministic SHAs. git-notes for rebase-safe commit mapping.
 
-Uses `toml_edit` to preserve comments, formatting, and structure:
-
-```toml
-# Your carefully written comments
-tokio = { version = "1.5" }  # ← stays exactly here
-```
+**Lossless TOML.** Uses `toml_edit` to preserve comments and formatting.
 
 ---
 
@@ -195,110 +71,77 @@ tokio = { version = "1.5" }  # ← stays exactly here
 | `split` | Extract crate to standalone repo with history |
 | `sync` | Bidirectional monorepo ↔ split repo sync |
 | `release` | Version bump, changelog, tag, publish |
-| `init` | Generate `rail.toml` configuration |
+| `init` | Generate `rail.toml` |
 | `check` | Validate release readiness |
 | `clean` | Remove generated artifacts |
-| `config` | Validate configuration file |
+| `config` | Validate configuration |
 
-Run `cargo rail <command> --help` for details, or see [docs/commands.md](docs/commands.md)
+Run `cargo rail <command> --help` for details, or see [docs/commands.md](docs/commands.md).
 
 ---
 
 ## Configuration
 
 ```bash
-cargo rail init  # Auto-detects targets, generates .config/rail.toml
+cargo rail init    # Generates .config/rail.toml
 ```
 
-Generated config with all options and defaults:
+Searched in order: `rail.toml`, `.rail.toml`, `.cargo/rail.toml`, `.config/rail.toml`
 
 ```toml
-# .config/rail.toml (or rail.toml, .rail.toml, .cargo/rail.toml)
-
-# Platform targets for multi-target validation (auto-detected from rust-toolchain.toml, .cargo/config.toml, etc.)
-targets = ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin", "x86_64-pc-windows-msvc"]
+targets = ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin"]
 
 [unify]
-include_paths = true           # Handle path dependencies (default: true)
-include_renamed = false        # Handle renamed deps with package = "..." (default: false)
-pin_transitives = false        # Pin transitive-only deps - enable for hakari users (default: false)
-transitive_host = "root"       # Where to put pinned transitive dev-deps: "root" or "crates/foo"
-exclude = []                   # Dependencies to skip unification
-include = []                   # Dependencies to force-include
-msrv = true                    # Compute workspace MSRV from deps (default: true)
-strict_version_compat = true   # Treat version mismatches as errors (default: true)
-exact_pin_handling = "warn"    # How to handle =x.y.z pins: skip, preserve, warn (default: warn)
-detect_unused = true           # Detect unused dependencies (default: true)
-remove_unused = true           # Auto-remove unused deps (default: true)
-max_backups = 3                # Number of backup files to keep (default: 3)
-prune_dead_features = true     # Remove features never enabled in graph (default: true)
+pin_transitives = false    # Enable for hakari/workspace-hack replacement
+prune_dead_features = true # Remove features never enabled in graph
+detect_unused = true       # Find deps not in resolved graph
+remove_unused = true       # Auto-remove unused deps
+msrv = true                # Compute workspace MSRV from deps
 
 [release]
-tag_prefix = "v"                        # Prefix for tags
-tag_format = "{crate}-{prefix}{version}" # Tag template: {crate}, {prefix}, {version}
-require_clean = true                    # Require clean working directory
-publish_delay = 5                       # Seconds between crates.io publishes
-create_github_release = false           # Create GitHub releases via gh CLI
-sign_tags = false                       # Sign tags with GPG/SSH
-changelog_path = "CHANGELOG.md"         # Path to changelog file
-changelog_relative_to = "crate"         # "crate" or "workspace"
-skip_changelog_for = []                 # Crates to skip changelog generation
-require_changelog_entries = false       # Error if no changelog entries
+tag_format = "{crate}-{prefix}{version}"
+create_github_release = false
+publish_delay = 5
 
 [change-detection]
-# Files that trigger full workspace rebuild
-infrastructure = [".github/**", "scripts/**", "justfile", "Makefile", "*.sh"]
-# custom.verify = ["verify/**/*.rs"]    # Custom path categories
+infrastructure = [".github/**", "justfile"]
 
-# Per-crate configuration
 [crates.my-crate.split]
 remote = "[email protected]:org/my-crate.git"
 branch = "main"
-mode = "single"  # single, combined, or monorepo
-
-[crates.my-crate.release]
-publish = true
+mode = "single"
 ```
 
+Full reference: [docs/config.md](docs/config.md)
+
+---
+
+## Real-World Impact
+
+`cargo rail unify` on tested monorepos:
+
+| Repository | Crates | Deps Unified | Edits Saved |
+|------------|--------|--------------|-------------|
+| [tikv](https://github.com/tikv/tikv) | 83 | 57 | 516 |
+| [meilisearch](https://github.com/meilisearch/meilisearch) | 19 | 46 | 209 |
+| [helix](https://github.com/helix-editor/helix) | 13 | 16 | 66 |
+| [tokio](https://github.com/tokio-rs/tokio) | 10 | 10 | 35 |
+| [ripgrep](https://github.com/BurntSushi/ripgrep) | 10 | 9 | 35 |
+
+See [examples/](examples/) for full results across 12 repositories.
+
 ---
 
 ## Replaces
 
-| Tool | What cargo-rail does instead |
-|------|------------------------------|
-| cargo-hakari | Resolution-based unification, no workspace-hack crate |
-| cargo-hackerman | Same — workspace-hack replacement via `pin_transitives` |
-| cargo-udeps | Unused dep detection via `detect_unused`, removal via `remove_unused` |
-| cargo-machete | Same — detects deps not in resolved graph |
-| cargo-shear | Same — unused dep detection and removal |
-| cargo-msrv | Auto-compute workspace MSRV via `msrv = true` |
-| cargo-release | Dependency-ordered publishing, native changelog |
-| release-plz | Same, with 600 fewer dependencies |
-| git-cliff | Built-in conventional commit parsing |
-| Copybara | Deterministic split/sync with git-notes |
-| CI shell scripts | Graph-aware `affected` with nextest integration |
-
-### cargo-rail vs cargo-hakari
-
-| Feature | cargo-hakari | cargo-rail |
-|---------|--------------|------------|
-| Requires extra crate | Yes (workspace-hack) | No |
-| Preserves TOML comments | No | Yes |
-| Multi-target aware | No | Yes |
-| Feature computation | Union (all features) | Intersection (minimal) |
-| Dependencies | ~40 via guppy | 12 |
-
-### cargo-rail vs release-plz
-
-| Feature | release-plz | cargo-rail |
-|---------|-------------|------------|
-| Version bumping | Yes | Yes |
-| Changelog generation | Yes | Yes |
-| Dependency ordering | Yes | Yes |
-| GitHub releases | Yes | Yes |
-| Dependencies | ~600 resolved | 12 |
-| Crate splitting | No | Yes |
-| Bidirectional sync | No | Yes |
+| Tool | cargo-rail equivalent |
+|------|----------------------|
+| cargo-hakari | `unify` with `pin_transitives = true` |
+| cargo-udeps / cargo-machete | `detect_unused = true`, `remove_unused = true` |
+| cargo-msrv | `msrv = true` |
+| cargo-release / release-plz | `release` command |
+| git-cliff | Built-in changelog generation |
+| Copybara | `split` + `sync` commands |
 
 ---
 

examples/ripgrep/README.md

@@ -29,7 +29,7 @@ cargo rail unify
 | Workspace members | **10** (not 1!) |
 | Dependencies unified | 9 |
 | Member edits | 35 |
-| Transitives pinned | 5 |
+| Dead features pruned | 11 |
 
 **Dependencies unified:** serde_json, regex, serde, bstr, memchr, termcolor, globset, walkdir, log
 

examples/tikv/README.md

@@ -28,10 +28,10 @@ cargo rail unify
 |--------|-------|
 | Workspace members | 83 |
 | Dependencies unified | 57 |
-| Member edits | **520** |
-| Dead features pruned | 156 |
+| Member edits | **516** |
+| Dead features pruned | 112 |
 
-**MASSIVE IMPACT:** 520 manual file edits automated!
+**MASSIVE IMPACT:** 516 manual file edits automated!
 
 ## Configuration
 
@@ -55,7 +55,7 @@ detect_unused = true
 - Distributed transactional key-value store (PingCAP)
 - Largest workspace tested (83 crates)
 - Shows cargo-rail's diagnostic capabilities (auto-detects and skips multi-version conflicts)
-- 520 file edits saved - massive enterprise impact
-- 156 dead features pruned
+- 516 file edits saved - massive enterprise impact
+- 112 dead features pruned
 
 Details in [`summary.toml`](./summary.toml).