Git browser: real .git files alongside virtual

Drop the `raw/` escape hatch and merge real `.git/*` entries (HEAD, config, hooks/, info/, objects/, packed-refs, refs/, …) directly into the portal root listing.

- `list_root` reads the resolved gitdir via `std::fs::read_dir` (follows gitlinks), filters out names colliding with virtual categories so the deprecated real `.git/branches/` and the `.git/worktrees/` internals stay hidden behind the friendly virtual entries, sorts dirs-first alphabetical, then appends the six virtual categories in fixed order.
- `Cat::Raw` and `VirtualGitPath::Raw` are gone. `path::classify` now returns `None` for any `.git/*` segment that isn't a virtual category, so the LocalPosixVolume real-FS path takes over for `HEAD`, `config`, `objects/`, etc. — no new code on the read side.
- `try_open_blob_stream` no longer needs a raw passthrough — real `.git/*` files stream through the standard local read path.
- Updated `git/CLAUDE.md` (file map, decisions block, M-overview), `volume/CLAUDE.md` (delegation hooks), `worktrees.rs` collision note, and CHANGELOG.
- New tests cover the mixed-listing shape, the dirs-first sort within real entries, and that real `.git/*` entries drop out of `classify`.

Author: vdavid

CHANGELOG.md

@@ -57,6 +57,13 @@ The format is based on [keep a changelog](https://keepachangelog.com/en/1.1.0/),
   `yml`/`yaml`, `tif`/`tiff`, `mpg`/`mpeg`, `mid`/`midi`, `aif`/`aiff`, `qt`/`mov`, `md`/`markdown`/`txt`) no longer
   trips the "you're changing the file type" confirmation. Cross-group changes still warn
   ([55592ba4](https://github.com/vdavid/cmdr/commit/55592ba4)).
+- **Git browser: real `.git/*` files alongside virtual entries.** Opening `.git/` now shows the real on-disk contents
+  (HEAD, config, hooks/, info/, objects/, packed-refs, refs/, ORIG_HEAD, …) sorted dirs-first alphabetical, followed by
+  the six virtual categories (branches, tags, commits, stash, worktrees, submodules) in fixed order. Real entries
+  navigate through the standard real-FS path; virtual entries route to the git module's tree-walking code. The previous
+  `raw/` escape hatch is gone — its contents are now one click away instead of two. The deprecated real `.git/branches/`
+  directory and the real `.git/worktrees/` in linked-worktree setups stay hidden behind the friendly virtual entries
+  with the same name.
 
 ### Fixed
 

apps/desktop/src-tauri/src/file_system/git/CLAUDE.md

@@ -2,18 +2,21 @@
 
 Backend module for the git browser. M1 shipped repo discovery, repo
 info, status, the watcher, and the friendly-error skeleton. M2 added
-the virtual `.git` portal – `branches/`, `tags/`, `raw/` browsable as
+the virtual `.git` portal – `branches/` and `tags/` browsable as
 virtual trees, with cross-volume copy "for free" because git blobs flow
 through the existing `VolumeReadStream` abstraction. M3 filled in
 commits, stash, worktrees, and submodules: the first two browse a
 commit tree just like branches/tags; the latter two surface
 `redirectToPath` so the frontend opens the worktree's / submodule's
-working dir directly. **M4 (this milestone) adds three things: a live
-toggle for the portal so `cd .git` can fall through to raw on-disk
-contents, FriendlyError integration end-to-end so every git failure
-reaches `ErrorPane` with a warm title + explanation + suggestion, and
-three new error variants (`ShallowBoundary`, `MissingObject`,
-`GitDirPermissionDenied`).**
+working dir directly. M4 added three things: a live toggle for the
+portal so `cd .git` can fall through to raw on-disk contents,
+FriendlyError integration end-to-end so every git failure reaches
+`ErrorPane` with a warm title + explanation + suggestion, and three
+new error variants (`ShallowBoundary`, `MissingObject`,
+`GitDirPermissionDenied`). **The portal root listing now mixes real
+`.git/*` entries (HEAD, config, hooks/, objects/, refs/, …) with the
+six virtual categories so the user sees everything in one place; the
+old `raw/` escape hatch is gone.**
 
 ## File map
 
@@ -22,7 +25,7 @@ three new error variants (`ShallowBoundary`, `MissingObject`,
 | `mod.rs` | Public API + the three volume hooks (`try_route_listing`, `try_route_metadata`, `try_open_blob_stream`) plus `is_virtual` for the mutation guards |
 | `repo.rs` | `discover_repo(path)` walking up via `gix::discover` (follows gitlinks). `repo_info(handle, root)` collects branch, detached SHA, unborn flag, upstream, ahead/behind, and `is_dirty`. Process-global `RepoCache` (`Arc<RwLock<HashMap>>`) keyed by canonical worktree root |
 | `path.rs` | `VirtualGitPath` enum, `Cat` enum, `classify(path)` parser, `to_path` inverse, `is_virtual(path)` for the volume hook short-circuits. Greedy ref-name match against the repo's known refs so `feature/foo` parses as one ref |
-| `virtual_listing.rs` | `list_root` (M2 exposes `branches/`, `tags/`, `raw/`), `list_branches`, `list_tags`, `list_raw` (real-FS passthrough), `get_metadata_for`, `resolve_ref_commit` (annotated tags peel through). Real-FS reads use `std::fs` to avoid recursing through the volume hook |
+| `virtual_listing.rs` | `list_root` (mixes real `.git/*` entries + the six virtual categories), `list_branches`, `list_tags`, `get_metadata_for`, `resolve_ref_commit` (annotated tags peel through), `real_gitdir_path` (follows gitlinks). Real-FS reads use `std::fs` to avoid recursing through the volume hook |
 | `log.rs` | `list_commits` – gix `rev_walk` over HEAD-reachable commits; cap 5000, batch 200, `#[cfg(test)]` cooperative cancel flag (production relies on `spawn_blocking` task abort). `resolve_commit_id` resolves a SHA prefix even for unreachable commits |
 | `stash.rs` | `list_stashes(repo_root)`, `resolve_stash_commit(handle, n)` – shells out to `git stash list -z` and `git rev-parse stash@{n}` (gix has no public stash API). `list_stashes` doesn't take a `RepoHandle` because the shell-out only needs `repo_root` for `git -C` |
 | `worktrees.rs` | `list_worktrees` – gix `Repository::worktrees()`. Each entry sets `redirect_to_path` to the worktree's working dir |
@@ -128,7 +131,6 @@ Every virtual entry carries a real `modified_at` and most carry a `display_size`
 | `.git/stash/` | newest stash creation date | `3 stash entries` | stash count |
 | `.git/worktrees/` | newest linked worktree HEAD | `2 linked worktrees` | worktree count |
 | `.git/submodules/` | newest pinned commit | `1 submodule` | submodule count |
-| `.git/raw/` | real `.git/` mtime | None (real bytes) | real bytes |
 | `branches/<name>/` | branch tip committer date | `+12 / -3` vs upstream (or fallback `main`/`master`) | ahead-count |
 | `tags/<name>/` | annotated tag date or commit date | short SHA | 0 |
 | `commits/<sha>/` | commit committer date | `5 files` (or `1 file`) | files-changed count |
@@ -147,6 +149,9 @@ The frontend reads `display_size` / `display_size_tooltip` from `FileEntry`; the
 
 ## Decisions
 
+**Decision**: Mixed real + virtual portal root listing; `raw/` escape hatch dropped
+**Why**: Hiding real `.git/*` contents behind a separate `raw/` category meant two extra clicks (open `.git/`, open `raw/`) for anyone wanting to peek at `HEAD`, `config`, `hooks/`, `objects/`, etc. The virtual entries already cover the friendly view; surfacing the real entries in the same listing gives power users one-click access without the `raw/` indirection. The classifier (`path::classify`) returns `None` for any `.git/*` segment that isn't a virtual category name, so the volume hook falls through to the real-FS path automatically — no new code on the read side, the existing LocalPosixVolume handles it. Real entries whose name collides with a virtual category get filtered out: the deprecated `.git/branches/` directory (git itself stopped writing to it years ago) and `.git/worktrees/` in linked-worktree setups (its internals belong to git, not to the user) hide behind the friendly virtual entries. Power users who really want the raw bytes open the gitdir from the terminal. Sort order: real entries dirs-first alphabetical (matching the listing pipeline default), then the six virtual categories in fixed order (branches, tags, commits, stash, worktrees, submodules).
+
 **Decision (M4 follow-up)**: Per-file Modified dates inside snapshot listings via walk-once batching
 **Why**: The snapshot date ("when this commit landed") is the same value for every file inside a `branches/main/`, `commits/<sha>/`, etc. listing — semantically correct as a "frozen point in time", but useless as a "when did I last work on this?" hint. We now run a single rev-walk per `(commit_id, dir_path)` listing: from the snapshot commit backwards by commit time, first-parent only, diffing each commit against its first parent (gix's `Tree::changes()::for_each_to_obtain_tree`). Each `Change.location` is matched against the directory's top-level entries; the first-seen commit's committer time wins. The walk stops early when every entry is dated, after `MAX_COMMITS_PER_WALK` (1000), or when the rev-walk exits. Initial commits short-circuit. Cache is process-global, FIFO-bounded at 50 keys, content-addressable so it never invalidates. Bench: 100 entries × 5000 commits cold p95=21 ms (budget 200 ms), warm p95=2 µs. 50k-commit fixture sits inside the 500 ms budget too. Entries that don't surface within the cap fall back to the snapshot date so the cell never reads as blank.
 

apps/desktop/src-tauri/src/file_system/git/m2_tests.rs

@@ -121,10 +121,17 @@ fn classify_and_round_trip() {
         VirtualGitPath::RefTree(Cat::Tags, "v1.0".into(), "README.md".into())
     );
 
-    // Raw passthrough.
-    let p = dot_git.join("raw").join("HEAD");
-    let (virt, _, _) = classify(&p).expect("classify raw");
-    assert_eq!(virt, VirtualGitPath::Raw("HEAD".into()));
+    // Real `.git/*` entries don't classify as virtual – the volume hook
+    // returns `None` and the LocalPosixVolume real-FS path takes over.
+    assert!(classify(&dot_git.join("HEAD")).is_none(), "HEAD is real, not virtual");
+    assert!(
+        classify(&dot_git.join("config")).is_none(),
+        "config is real, not virtual"
+    );
+    assert!(
+        classify(&dot_git.join("refs").join("heads").join("main")).is_none(),
+        "refs/ is real, not virtual"
+    );
 
     cleanup(&dir);
 }
@@ -154,16 +161,92 @@ fn list_tags_yields_v1() {
 }
 
 #[test]
-fn list_root_includes_all_categories() {
-    // M3 added commits/stash/worktrees/submodules to the root listing.
+fn list_root_mixes_real_and_virtual_entries() {
+    // The portal root surfaces real `.git/*` files (HEAD, config, hooks/,
+    // objects/, refs/) followed by the six virtual category entries
+    // (branches, tags, commits, stash, worktrees, submodules) in fixed
+    // order. Real entries that collide with a virtual category name get
+    // filtered out so the virtual one wins.
     let dir = build_fixture_repo();
     let (handle, root) = discover_repo(&dir).unwrap();
     let entries = virtual_listing::list_root(&handle, &root);
     let names: Vec<_> = entries.iter().map(|e| e.name.as_str()).collect();
-    assert_eq!(
-        names,
-        vec!["branches", "tags", "commits", "stash", "worktrees", "submodules", "raw"]
-    );
+
+    // Real `.git/*` entries appear (every fresh git init creates these).
+    for must_have in ["HEAD", "config", "hooks", "info", "objects", "refs"] {
+        assert!(
+            names.contains(&must_have),
+            "real .git/{} must show up in the root listing: got {:?}",
+            must_have,
+            names
+        );
+    }
+
+    // The six virtual categories appear in fixed order, after every real
+    // entry.
+    let virtual_order = ["branches", "tags", "commits", "stash", "worktrees", "submodules"];
+    let positions: Vec<usize> = virtual_order
+        .iter()
+        .map(|n| {
+            names
+                .iter()
+                .position(|x| x == n)
+                .unwrap_or_else(|| panic!("virtual entry {} missing from {:?}", n, names))
+        })
+        .collect();
+    assert_eq!(positions, (names.len() - 6..names.len()).collect::<Vec<_>>());
+    for w in positions.windows(2) {
+        assert!(w[0] < w[1], "virtual entries should keep fixed order: {:?}", positions);
+    }
+
+    // Collision filter: the deprecated real `.git/branches/` directory
+    // must not show up as a real entry. The virtual `branches/` is the
+    // only entry called `branches` in the listing.
+    let branches_count = names.iter().filter(|n| **n == "branches").count();
+    assert_eq!(branches_count, 1, "virtual branches/ takes precedence over real one");
+
+    // `raw/` should not appear anywhere – we dropped it in favour of the
+    // mixed real + virtual listing.
+    assert!(!names.contains(&"raw"), "raw/ category was removed");
+
+    cleanup(&dir);
+}
+
+#[test]
+fn list_root_real_entries_sort_dirs_first_alpha() {
+    let dir = build_fixture_repo();
+    let (handle, root) = discover_repo(&dir).unwrap();
+    let entries = virtual_listing::list_root(&handle, &root);
+
+    // Slice off the trailing six virtual entries; everything before is real.
+    let real = &entries[..entries.len() - 6];
+
+    // Dirs come before files.
+    let last_dir = real.iter().rposition(|e| e.is_directory);
+    let first_file = real.iter().position(|e| !e.is_directory);
+    if let (Some(ld), Some(ff)) = (last_dir, first_file) {
+        assert!(ld < ff, "dirs must come before files in real entries: {:?}", real);
+    }
+
+    // Within dirs and within files, alphabetical (case-insensitive).
+    let dir_names: Vec<String> = real
+        .iter()
+        .filter(|e| e.is_directory)
+        .map(|e| e.name.to_lowercase())
+        .collect();
+    let mut sorted = dir_names.clone();
+    sorted.sort();
+    assert_eq!(dir_names, sorted, "real dirs must sort alphabetically");
+
+    let file_names: Vec<String> = real
+        .iter()
+        .filter(|e| !e.is_directory)
+        .map(|e| e.name.to_lowercase())
+        .collect();
+    let mut sorted = file_names.clone();
+    sorted.sort();
+    assert_eq!(file_names, sorted, "real files must sort alphabetically");
+
     cleanup(&dir);
 }
 
@@ -225,24 +308,17 @@ async fn blob_stream_drains_to_full_blob() {
     cleanup(&dir);
 }
 
-#[test]
-fn raw_passthrough_lists_real_gitdir() {
-    let dir = build_fixture_repo();
-    let (_, root) = discover_repo(&dir).unwrap();
-    let entries = virtual_listing::list_raw(&root, "").expect("list_raw");
-    let names: Vec<_> = entries.iter().map(|e| e.name.as_str()).collect();
-    assert!(names.contains(&"HEAD"));
-    assert!(names.contains(&"refs"));
-    cleanup(&dir);
-}
-
 #[test]
 fn is_virtual_routes_through_volume_hooks() {
     let dir = build_fixture_repo();
     let (_, root) = discover_repo(&dir).unwrap();
+    // `is_virtual` is the mutation-guard cheap shape check: any path with
+    // `.git` in it counts. That's by design – we never want to write to
+    // `.git/HEAD` from a copy dialog, even though it's a real on-disk file.
     assert!(is_virtual(&root.join(".git")));
     assert!(is_virtual(&root.join(".git/branches")));
     assert!(is_virtual(&root.join(".git/branches/main/README.md")));
+    assert!(is_virtual(&root.join(".git/HEAD")));
     assert!(!is_virtual(&root.join("scripts/run.sh")));
     cleanup(&dir);
 }

apps/desktop/src-tauri/src/file_system/git/m4_tests.rs

@@ -112,8 +112,11 @@ fn root_listing_populates_size_with_item_counts() {
         "commits/ display says 'commits'"
     );
 
-    let raw = by_name["raw"];
-    assert!(raw.modified_at.is_some(), "raw/ Modified comes from .git/ mtime");
+    // Real `.git/*` entries land in the mixed listing too. HEAD is the
+    // canary: every fresh git init writes one.
+    let head = by_name.get("HEAD").expect("real .git/HEAD shows up in root");
+    assert!(!head.is_directory, "HEAD is a real file");
+    assert!(head.modified_at.is_some(), "real entries carry stat mtime");
 
     cleanup(&dir);
 }

apps/desktop/src-tauri/src/file_system/git/mod.rs

@@ -2,16 +2,22 @@
 //!
 //! M1 ships repo detection, repo info, status, the `.git/*` watcher, and
 //! friendly-error mapping. M2 adds the virtual portal: `branches/`,
-//! `tags/`, `raw/` browsable as virtual trees, with cross-volume copy
-//! "for free" because git blobs flow through the existing `VolumeReadStream`
-//! abstraction.
+//! `tags/`, `commits/`, `stash/`, `worktrees/`, `submodules/` browsable
+//! as virtual trees, with cross-volume copy "for free" because git blobs
+//! flow through the existing `VolumeReadStream` abstraction. The portal
+//! root listing also surfaces real `.git/*` entries (HEAD, config,
+//! hooks/, objects/, refs/, …) alongside the virtual categories – the
+//! user sees everything in one place and navigates real entries through
+//! the standard real-FS path.
 //!
-//! ## Volume hook contract (M2)
+//! ## Volume hook contract
 //!
 //! `LocalPosixVolume` calls `git::try_route_*` after `resolve()`. Order is
 //! load-bearing: `resolve` normalizes the absolute path, then we classify
 //! against any enclosing `.git/`. If a virtual path matches we return its
-//! result; otherwise the volume falls through to real-FS code.
+//! result; otherwise (real `.git/*` entries, or paths outside any `.git/`)
+//! the classifier returns `None` and the volume falls through to real-FS
+//! code.
 //!
 //! All mutation methods short-circuit virtual paths via `path::is_virtual`
 //! and return `VolumeError::NotSupported`. Git mutations happen out-of-band
@@ -112,7 +118,9 @@ pub fn is_virtual_portal_enabled() -> bool {
 /// Volume hook for `list_directory`.
 ///
 /// Returns `Some(result)` when the path lives under a virtual `.git/...`
-/// portal; `None` when the caller should run real-FS code.
+/// portal; `None` when the caller should run real-FS code (real `.git/*`
+/// entries like `HEAD`, `config`, `objects/`, etc., and paths outside any
+/// `.git/`).
 pub fn try_route_listing(path: &Path) -> Option<Result<Vec<FileEntry>, VolumeError>> {
     if !is_virtual_portal_enabled() {
         return None;
@@ -127,14 +135,12 @@ pub fn try_route_listing(path: &Path) -> Option<Result<Vec<FileEntry>, VolumeErr
         Category(path::Cat::Stash) => stash::list_stashes(&root),
         Category(path::Cat::Worktrees) => worktrees::list_worktrees(&handle, &root),
         Category(path::Cat::Submodules) => submodules::list_submodules(&handle, &root),
-        Category(path::Cat::Raw) => virtual_listing::list_raw(&root, ""),
         Ref(cat, name) if cat.browses_commit_tree() => list_ref_tree(&handle, &root, *cat, name, ""),
         RefTree(cat, name, sub) if cat.browses_commit_tree() => list_ref_tree(&handle, &root, *cat, name, sub),
         // Worktrees and submodules are leaf entries with `redirectToPath`;
         // listing them as if they were directories returns empty (the
         // frontend redirects on Enter so this rarely fires in practice).
         Ref(_, _) | RefTree(_, _, _) => Ok(Vec::new()),
-        Raw(sub) => virtual_listing::list_raw(&root, sub),
     };
     Some(result.map_err(friendly_to_volume_error))
 }
@@ -150,12 +156,13 @@ pub fn try_route_metadata(path: &Path) -> Option<Result<FileEntry, VolumeError>>
 }
 
 /// Volume hook for `open_read_stream`. Returns `None` for paths that aren't
-/// virtual blobs.
+/// virtual blobs (real `.git/*` files fall through to the real-FS reader
+/// via the volume hook returning `None`).
 pub fn try_open_blob_stream(path: &Path) -> Option<Result<Box<dyn VolumeReadStream>, VolumeError>> {
     if !is_virtual_portal_enabled() {
         return None;
     }
-    let (virt, handle, root) = path::classify(path)?;
+    let (virt, handle, _root) = path::classify(path)?;
     use path::VirtualGitPath::*;
     let result = match &virt {
         RefTree(cat, name, sub) if cat.browses_commit_tree() => {
@@ -170,11 +177,6 @@ pub fn try_open_blob_stream(path: &Path) -> Option<Result<Box<dyn VolumeReadStre
             tree::read_blob(&handle, blob_id)
                 .map(|bytes| Box::new(read_blob::GitBlobReadStream::new(bytes)) as Box<dyn VolumeReadStream>)
         }
-        Raw(sub) if !sub.is_empty() => {
-            // Real-FS file under .git/raw/...
-            let real = virtual_listing::real_gitdir_path(&root, sub);
-            return Some(open_real_file_stream(&real));
-        }
         _ => return Some(Err(VolumeError::NotSupported)),
     };
     Some(result.map_err(friendly_to_volume_error))
@@ -213,18 +215,13 @@ pub(crate) fn resolve_commit_for_cat(
                 .map_err(|_| FriendlyGitError::new(FriendlyGitErrorKind::CorruptRepo, name.to_string()))?;
             stash::resolve_stash_commit(handle, n)
         }
-        _ => Err(FriendlyGitError::new(
+        path::Cat::Worktrees | path::Cat::Submodules => Err(FriendlyGitError::new(
             FriendlyGitErrorKind::CorruptRepo,
             name.to_string(),
         )),
     }
 }
 
-fn open_real_file_stream(real: &Path) -> Result<Box<dyn VolumeReadStream>, VolumeError> {
-    let bytes = std::fs::read(real).map_err(VolumeError::from)?;
-    Ok(Box::new(read_blob::GitBlobReadStream::new(bytes)) as Box<dyn VolumeReadStream>)
-}
-
 fn friendly_to_volume_error(err: FriendlyGitError) -> VolumeError {
     // Carry the structured payload through the typed variant so the listing
     // pipeline's friendly-error mapper rebuilds a fully-shaped `FriendlyError`