cargo-rail: fixing the codex-rs bug for nested workspaces under change detection; updating the readme/docs/etc.

Author: loadingalias

README.md

@@ -37,9 +37,9 @@ cargo-rail is a single tool that replaces a fragmented ecosystem:
 | **MSRV guessing** | `cargo-msrv`, compile-and-fail loops | `cargo rail unify` |
 | **CI waste** | `paths-filter` + 1k LoC shell | `cargo rail test` |
 | **Crate extraction** | `git subtree`, Copybara (Java) | `cargo rail split` |
-| **Release chaos** | `release-plz` (600+ deps), `git-cliff` | `cargo rail release` |
+| **Release chaos** | `release-plz` (hundreds of deps), `git-cliff` | `cargo rail release` |
 
-**11 core dependencies. 77 resolved. One config file.**
+**11 core dependencies. 55 resolved. One config file.**
 
 ---
 
@@ -58,13 +58,15 @@ Pre-built binaries: [Releases](https://github.com/loadingalias/cargo-rail/releas
 Drop into any Rust workspace:
 
 ```bash
-cargo rail init              # Generate .config/rail.toml
-cargo rail unify --check     # Preview dependency unification
-cargo rail unify             # Apply (auto-backups on first run)
-cargo rail test              # Test only affected crates
+cargo install cargo-rail && cargo rail init
+cargo rail unify --check     # See what would change (read-only)
 ```
 
-That's it. Your workspace is now unified, and you're only testing what changed.
+That's it. See what cargo-rail would unify — no changes made until you run `cargo rail unify`.
+
+https://github.com/user-attachments/assets/93f34633-aa0e-4cde-8723-c81f3f474bac
+
+<sub>*`cargo rail unify` on ripgrep — 9 deps unified, 6 dead features pruned*</sub>
 
 ---
 
@@ -102,7 +104,7 @@ cargo rail test --all            # Override: test everything
 **For CI:** Use [`cargo-rail-action`](https://github.com/loadingalias/cargo-rail-action):
 
 ```yaml
-- uses: loadingalias/cargo-rail-action@v1
+- uses: loadingalias/cargo-rail-action@latest
   id: rail
   with:
     since: ${{ github.event.before }}
@@ -135,11 +137,11 @@ What it does:
 Extract crates with full git history. Keep them in sync:
 
 ```bash
-cargo rail split init my_crate      # Configure
-cargo rail split run my_crate       # Extract with history
-cargo rail sync my_crate            # Bidirectional sync
-cargo rail sync my_crate --to-remote    # Push to split repo
-cargo rail sync my_crate --from-remote  # Pull (creates PR branch)
+cargo rail split init my-crate      # Configure
+cargo rail split run my-crate       # Extract with history
+cargo rail sync my-crate            # Bidirectional sync
+cargo rail sync my-crate --to-remote    # Push to split repo
+cargo rail sync my-crate --from-remote  # Pull (creates PR branch)
 ```
 
 Three modes: single crate → new repo, multiple crates → new repo, or multiple crates → new workspace.
@@ -168,7 +170,7 @@ Tested on production Rust workspaces:
 | **[helix](https://github.com/loadingalias/helix)** | 12 | 16 | 1 | Editor workspace |
 | **[tokio](https://github.com/loadingalias/tokio)** | 10 | 10 | 0 | Core ecosystem |
 | **[ripgrep](https://github.com/loadingalias/ripgrep)** | 10 | 9 | 6 | CLI baseline |
-| **[polars](https://github.com/loadingalias/polars)** | 8 | 2 | 9 | Already clean |
+| **[polars](https://github.com/loadingalias/polars)** | 33 | 2 | 9 | Already clean |
 | **[ruff](https://github.com/loadingalias/ruff)** | 43 | 0 | 0 | Already unified |
 | **[codex](https://github.com/loadingalias/codex)** | 49 | 0 | 0 | Already unified |
 
@@ -203,7 +205,27 @@ Full guide: [docs/migrate-hakari.md](docs/migrate-hakari.md)
 
 **Lossless TOML** — Uses `toml_edit` to preserve comments and formatting. Your manifests stay readable.
 
-**Supply-Chain Safety** — 11 core dependencies. I built the release workflow specifically because I was uncomfortable with 600+ deps for release automation.
+**Supply-Chain Safety** — 11 core dependencies. I built the release workflow specifically because I was uncomfortable with hundreds of deps for release automation.
+
+---
+
+## FAQ
+
+**How is this different from cargo-hakari?**
+
+cargo-hakari creates a workspace-hack crate. cargo-rail writes unified versions directly to `[workspace.dependencies]` — no extra crate, no `hakari generate` step. Enable `pin_transitives = true` for equivalent behavior. See the [migration guide](docs/migrate-hakari.md).
+
+**Does it work with workspace inheritance?**
+
+Yes. cargo-rail writes to `[workspace.dependencies]` and converts member manifests to `{ workspace = true }`.
+
+**What about virtual workspaces?**
+
+Supported. For `pin_transitives`, cargo-rail auto-selects a workspace member as the transitive host (or set `transitive_host` explicitly).
+
+**Private registries?**
+
+Works via `cargo metadata`, which respects `.cargo/config.toml`. Private registry deps are pinned normally.
 
 ---
 
@@ -220,7 +242,7 @@ Full guide: [docs/migrate-hakari.md](docs/migrate-hakari.md)
 
 Issues, PRs, and feedback welcome. This is built for the Rust community.
 
-If cargo-rail helps your workflow, consider [starring the repo](https://github.com/loadingalias/cargo-rail) — it helps others find it.
+Found this useful? [Star the repo](https://github.com/loadingalias/cargo-rail) to help other Rust teams find it.
 
 ---
 

examples/release/README.md

@@ -1,6 +1,6 @@
 # release demo
 
-Demonstrates release validation and planning using tikv (70+ component workspace).
+Demonstrates release validation and planning using tikv (72 component workspace).
 
 ## Workflow
 

examples/unify/polars/README.md

@@ -1,6 +1,6 @@
 # polars unify demo
 
-Large data processing workspace (50+ crates, pyo3 bindings). Aggressive settings.
+Large data processing workspace (33 crates, pyo3 bindings). Aggressive settings.
 
 ## Config choices
 
@@ -31,7 +31,7 @@ major_version_conflict = "bump"
 
 ## What this shows
 
-- Handling large workspace with 50+ crates
+- Handling large workspace with 33 crates
 - `pin_transitives` as cargo-hakari replacement
 - Aggressive `major_version_conflict = "bump"` for leaner graph
 - polars already uses `[workspace.dependencies]` - cargo-rail enhances it

examples/unify/ripgrep/README.md

@@ -1,6 +1,6 @@
 # ripgrep unify demo
 
-Small, focused CLI workspace (9 crates). Demonstrates baseline unification.
+Small, focused CLI workspace (10 crates). Demonstrates baseline unification.
 
 ## Config choices
 

src/commands/affected.rs

@@ -255,24 +255,28 @@ fn write_output(content: &str, output_file: Option<&PathBuf>) -> RailResult<()>
   Ok(())
 }
 
-/// Get changed files from git
+/// Get changed files from git, normalized to workspace-relative paths
 fn get_changed_files(
   ctx: &WorkspaceContext,
   since: &str,
   from: Option<&str>,
   to: Option<&str>,
 ) -> RailResult<Vec<PathBuf>> {
   // Determine git range
-  let changes = if let (Some(from_ref), Some(to_ref)) = (from, to) {
+  let git_changes = if let (Some(from_ref), Some(to_ref)) = (from, to) {
     // SHA pair mode: from..to
     ctx.git.git().get_changed_files_between(from_ref, Some(to_ref))?
   } else {
     // Single ref mode: since..working tree
     ctx.git.git().get_changed_files_between(since, None)?
   };
 
-  // Extract just the file paths (ignore status char)
-  let files = changes.into_iter().map(|(path, _status)| path).collect();
+  // Convert git-relative paths to workspace-relative paths
+  // This handles nested workspaces (e.g., git at /repo, workspace at /repo/rust)
+  let files = git_changes
+    .into_iter()
+    .filter_map(|(git_path, _status)| ctx.to_workspace_path(&git_path))
+    .collect();
 
   Ok(files)
 }

src/workspace/change_analyzer.rs

@@ -122,13 +122,25 @@ impl<'a> ChangeImpact<'a> {
   ///
   /// If `to` is None, compares against the working tree (uncommitted changes).
   pub fn analyze_changes(&self, from: &str, to: Option<&str>) -> RailResult<ImpactReport> {
-    // 1. Get changed files from git
-    let changed_files = self.ctx.git.git().get_changed_files_between(from, to)?;
-
-    // 2. Categorize changes by file type using new classification system
+    // 1. Get changed files from git (paths are relative to git root)
+    let git_changed_files = self.ctx.git.git().get_changed_files_between(from, to)?;
+
+    // 2. Convert git-relative paths to workspace-relative paths
+    //    This handles nested workspaces (e.g., git at /repo, workspace at /repo/rust)
+    let changed_files: Vec<(PathBuf, char)> = git_changed_files
+      .into_iter()
+      .filter_map(|(git_path, change_type)| {
+        self
+          .ctx
+          .to_workspace_path(&git_path)
+          .map(|ws_path| (ws_path, change_type))
+      })
+      .collect();
+
+    // 3. Categorize changes by file type using new classification system
     let categories = self.categorize_changes(&changed_files);
 
-    // 3. Use graph to find affected crates
+    // 4. Use graph to find affected crates
     let file_paths: Vec<PathBuf> = changed_files.iter().map(|(p, _)| p.clone()).collect();
     let analysis = crate::graph::analyze(&self.ctx.graph, &file_paths)?;
 

src/workspace/context.rs

@@ -420,6 +420,42 @@ impl WorkspaceContext {
   pub fn workspace_root(&self) -> &Path {
     &self.workspace_root
   }
+
+  /// Get the relative path from git root to workspace root.
+  ///
+  /// Returns `Some(prefix)` if workspace is nested inside git repo (e.g., "codex-rs"),
+  /// or `None` if they're the same directory.
+  ///
+  /// This is used to strip the prefix from git-relative paths so they can be
+  /// matched against workspace-relative paths (e.g., for crate membership).
+  pub fn workspace_prefix(&self) -> Option<PathBuf> {
+    let git_root = self.git.repo_root();
+
+    // If workspace is nested inside git repo, compute the relative prefix
+    if let Ok(prefix) = self.workspace_root.strip_prefix(git_root) {
+      if prefix.as_os_str().is_empty() {
+        None // Same directory
+      } else {
+        Some(prefix.to_path_buf())
+      }
+    } else {
+      None
+    }
+  }
+
+  /// Convert a git-relative path to a workspace-relative path.
+  ///
+  /// If the workspace is nested inside the git repo (e.g., git at `/repo`, workspace at `/repo/rust`),
+  /// git returns paths like `rust/src/lib.rs` but the workspace expects `src/lib.rs`.
+  ///
+  /// Returns `None` if the path doesn't belong to this workspace.
+  pub fn to_workspace_path(&self, git_path: &Path) -> Option<PathBuf> {
+    if let Some(prefix) = self.workspace_prefix() {
+      git_path.strip_prefix(&prefix).ok().map(|p| p.to_path_buf())
+    } else {
+      Some(git_path.to_path_buf())
+    }
+  }
 }
 
 #[cfg(test)]