From 44920109f20064d2f796db6f544060b8fad23a92 Mon Sep 17 00:00:00 2001
From: l0ng-ai <24760907+l0ng-ai@users.noreply.github.com>
Date: Mon, 7 Sep 2026 22:19:19 +0800
Subject: [PATCH] docs(scm): name what actually splits the two spellings of a
 repo root
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The three gates left on for Windows all blamed the slash direction: git
for Windows is MSYS2 and prints `C:/Users/...`, the OS spells it
`C:\Users\...`. That reading is wrong, and #796 pinned why — `Path`
compares by component, so `C:/x` and `C:\x` are already equal. What the
tests actually hold is `fs::canonicalize`'s answer, `\?\C:\Users\...`,
whose prefix component is `VerbatimDisk` where git's parses as `Disk`.

Comment-only. The gates stay exactly where they are; only the reason
written at each of them changes, so that whoever lifts them after #796
lands is not chasing slashes.
---
 src/ui/diff_overlay.rs | 18 +++++++++++-------
 src/ui/scm/detail.rs   | 16 +++++++++-------
 src/ui/scm/panel.rs    | 11 +++++++----
 3 files changed, 27 insertions(+), 18 deletions(-)

diff --git a/src/ui/diff_overlay.rs b/src/ui/diff_overlay.rs
index 016d3fd7..41401cfb 100644
--- a/src/ui/diff_overlay.rs
+++ b/src/ui/diff_overlay.rs
@@ -2470,13 +2470,17 @@ mod overlay_gpui_tests {
 /// the repository has left. That is what the stale entry below stands for.
 ///
 /// Unix-only, and not for the harness: on Windows the repository root git
-/// reports (`C:/Users/—`, forward slashes, straight out of MSYS2 git) is
-/// not the root the seeded cache below holds, so `scm_epoch` never agrees
-/// with the landing snapshot and the overlay re-probes on every frame —
-/// `load` reaches `Ready` and `loading` goes straight back to `true`,
-/// which is the exact spin this test exists to catch. That is a real
-/// divergence in the SCM layer's path comparisons rather than a test
-/// artefact, so the gate stays until those roots are compared normalised.
+/// reports (`C:/Users/—`, straight out of MSYS2 git) is not the root the
+/// seeded cache below holds. Not for the slash direction — `Path` compares
+/// by component, so `C:/x` and `C:\x` are already equal. The splitter is
+/// the prefix: the seeded root came past `fs::canonicalize`, which spells
+/// it `\\?\C:\Users\—` and makes its prefix component `VerbatimDisk` where
+/// git's answer parses as `Disk`. So `scm_epoch` never agrees with the
+/// landing snapshot and the overlay re-probes on every frame — `load`
+/// reaches `Ready` and `loading` goes straight back to `true`, which is the
+/// exact spin this test exists to catch. That is a real divergence in the
+/// SCM layer's path comparisons rather than a test artefact, so the gate
+/// stays until those roots are keyed by one spelling (#796).
 #[cfg(all(test, unix))]
 mod render_idle_gpui_tests {
     use super::*;
diff --git a/src/ui/scm/detail.rs b/src/ui/scm/detail.rs
index 16c27337..5bc2eff2 100644
--- a/src/ui/scm/detail.rs
+++ b/src/ui/scm/detail.rs
@@ -977,13 +977,15 @@ mod tests {
 ///
 /// Still unix-only, and for a reason worth naming rather than a harness
 /// one: on Windows `git rev-parse --show-toplevel` (Git for Windows is
-/// MSYS2) prints `C:/Users/—` with forward slashes, and that string is
-/// what `tty7_core::core::git::probe` stores as `RepoSnapshot::root`.
-/// Every comparison here — and in the SCM cache — is a plain `PathBuf`
-/// equality against a path the OS spelled `C:\Users\`, so the two never
-/// match and the panel never settles on the directory it is already
-/// showing. Taking the gate off needs those roots compared normalised,
-/// the way `ui::path_display` already normalises for display.
+/// MSYS2) prints `C:/Users/—`, and that string is what
+/// `tty7_core::core::git::probe` stores as `RepoSnapshot::root`. The
+/// forward slashes are not what breaks it — `Path` compares by component,
+/// so `C:/x` and `C:\x` are equal. The prefix is: `scratch` below hands the
+/// pane `fs::canonicalize`'s `\\?\C:\Users\—`, whose prefix component is
+/// `VerbatimDisk` where git's answer parses as `Disk`, so the plain
+/// `PathBuf` equalities here — and in the SCM cache — never match and the
+/// panel never settles on the directory it is already showing. Taking the
+/// gate off needs those roots keyed by one spelling (#796).
 #[cfg(all(test, unix))]
 mod detail_gpui_tests {
     use super::*;
diff --git a/src/ui/scm/panel.rs b/src/ui/scm/panel.rs
index abb15b97..ed15602a 100644
--- a/src/ui/scm/panel.rs
+++ b/src/ui/scm/panel.rs
@@ -2975,10 +2975,13 @@ mod render_idle_gpui_tests {
     }
 
     /// The only test in this module that waits on `repo.root`, and so the
-    /// only one Windows cannot run: git spells that root `C:/Users/—` and
-    /// the pane's own cwd is spelled `C:\Users\`, so the equality below
-    /// never holds there. Its sibling keys off the pane's cwd instead, and
-    /// runs everywhere.
+    /// only one Windows cannot run: git spells that root `C:/Users/—`, which
+    /// parses to a `Disk` prefix, while the pane's cwd came out of `scratch`
+    /// above — `fs::canonicalize`, so `\\?\C:\Users\—` and a `VerbatimDisk`
+    /// prefix — and the equality below never holds between the two. The
+    /// slashes are the red herring here; `Path` compares by component, so
+    /// `C:/x` and `C:\x` are equal. Its sibling keys off the pane's cwd
+    /// instead, and runs everywhere.
     #[cfg(unix)]
     #[gpui::test]
     fn a_settled_source_control_panel_reaches_render_idle(cx: &mut TestAppContext) {