Skip to content

Keep a project’s own checkout visible through path aliases - #37233

Closed
brennanb2025 wants to merge 11 commits into
mainfrom
brennanb2025/symlink-project-checkout-1101
Closed

brennanb2025 wants to merge 11 commits into
mainfrom
brennanb2025/symlink-project-checkout-1101

Conversation

@brennanb2025

@brennanb2025 brennanb2025 commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 2 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​536 0 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​536
Prod 19 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​260 $\color{#cf222e}{\Huge{\mathbf{−}}}$​70 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​190

The problem

If you created or cloned a Git project inside a folder reached through a symlink (for example ~/code pointing at another disk, macOS's /tmp, or a Windows junction), the project showed up with no workspace at all. Orca saved the path as you typed it, but Git reports the project's checkout at its real location. Orca compared the two as plain text, decided the checkout belonged to some other project, and the default "hide external worktrees" setting hid it. Add Project didn't have this problem because it already saves the location Git reports.

What changes for users

  • Create Project and Clone, from the desktop app and from a paired host, CLI or web client, now save the project at the location Git reports, the same way Add Project does. The project's checkout shows up and opens right away.
  • Projects already saved through a symlinked path now show their own checkout again. This includes projects that were registered at a linked worktree. Nothing saved is rewritten: workspace IDs, tabs, history and project settings stay as they are.
  • Running Create or Clone again through the original symlinked path returns the project you already have instead of failing or adding a duplicate. Importing nested repositories through a symlinked folder recognizes projects that are already added.
  • Other projects' worktrees stay hidden under the "hide" setting, as before.

How it works

  • New projects store Git's own root (git rev-parse --show-toplevel). The other entry points then find them through the existing same-folder check, which resolves symlinks.
  • For projects already saved, each worktree scan resolves the saved folder's real location once, in the background, alongside the Git listing. It then marks the checkout Git lists at that location as the project's own. Visibility checks only read that mark, so they never touch the disk. A symlink that is retargeted is picked up on the next scan. If a scan is slow, the rows Orca shows from saved data use the same result once it is available.
  • WSL network paths are never resolved in the background, because touching them can start a stopped distro. SSH projects never touch the local disk. The same-folder check skips WSL projects that can't be the same folder, so creating a project no longer touches unrelated WSL distros.

Visible differences (intended)

  • A project created through a symlinked folder now shows its real location in Settings and project pickers, matching Add Project. Workspace IDs, tabs and history are keyed on the location Git reports, so storing that location keeps them consistent.
  • On WSL and mapped network drives, new projects store the path Git reports, as Add Project already does. For example, \\wsl$\… becomes \\wsl.localhost\…, a \\wsl.localhost\<distro>\mnt\c\… path becomes C:\…, and a mapped drive letter becomes its \\server\share\… path.
  • Creating a project at a path that only matches an SSH project's path now creates the local project instead of returning the remote one. The lookup is now limited to this machine, like the paired-host path already was.
  • Existing WSL network-path projects saved through an alias keep their current behavior.
  • After a symlink is retargeted between two checkouts of the same repository, a paired host can keep showing the earlier checkout as the project's own for up to its existing five-minute refresh window. The desktop updates on its next scan.

No settings, saved fields or protocol messages are added.

Verification

  • Tests use real Git and real symlinks (junctions on Windows) and cover:
    • Create and Clone through both the desktop and paired-host entry points, including repeated requests;
    • saved alias projects, including one registered at a linked worktree, with their IDs and saved details unchanged and sibling worktrees still hidden;
    • slow scans;
    • retargeted symlinks;
    • nested import;
    • macOS /tmp.
  • Contract tests check that the work stays bounded: one resolution per local project per scan (3 and 30 projects), none for WSL or folder projects, and no disk access when classifying cached rows (10 and 100 worktrees).
  • QA evidence: the same test file ran on a real Windows machine (Git for Windows 2.55, Node 24, real directory junctions) and passed 12/12; the macOS-only /tmp case was skipped there.
  • The existing creation, clone, runtime-query, folder-upgrade and path-comparison tests pass.

Tracked in STA-13215: https://linear.app/stably/issue/STA-13215/git-projects-created-through-symlinked-paths-hide-their-own-checkout

@brennanb2025
brennanb2025 marked this pull request as ready for review November 1, 2026 23:40
@coderabbitai

coderabbitai Bot commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 4 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: faca720c-e93d-4f78-966e-0824f851213c
Commits

Reviewing files that changed from the base of the PR and between b3a8137 and 3a24ce1.

Files selected for processing: 21
  • config/tsconfig.tc.web.json
  • src/main/ipc/repos-create.test.ts
  • src/main/ipc/repos-symlink-checkout.test.ts
  • src/main/ipc/repos/nested-repo-import-handler.ts
  • src/main/ipc/repos/repo-clone-lifecycle.ts
  • src/main/ipc/repos/repo-creation-handlers.ts
  • src/main/ipc/worktree-metadata-merge.ts
  • src/main/ipc/worktree-project-checkout-mark.ts
  • src/main/ipc/worktrees/listing/detected-worktree-scan-cache.ts
  • src/main/ipc/worktrees/listing/ssh-worktree-fallback.ts
  • src/main/project-realpath-identity.ts
  • src/main/runtime/orca-runtime-core.ts
  • src/main/runtime/repo-worktree-resolution-scan.ts
  • src/main/runtime/repo-worktree-row-resolution.ts
  • src/main/runtime/runtime-managed-worktree-queries.ts
  • src/main/runtime/runtime-nested-repo-import.ts
  • src/main/runtime/runtime-repository-clone-controller.ts
  • src/main/runtime/runtime-repository-registration-controller.ts
  • src/main/runtime/workspaces/workspace-catalog.ts
  • src/main/runtime/workspaces/workspace-repo-scan-refresh.ts
  • src/shared/worktree/ownership.ts

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: cdb84bc2-4c01-4e8a-a25f-622f56546507
Commits

Reviewing files that changed from the base of the PR and between 1cc843e and b3a8137.

Files selected for processing: 19
  • src/main/ipc/repos-create.test.ts
  • src/main/ipc/repos-symlink-checkout.test.ts
  • src/main/ipc/repos/nested-repo-import-handler.ts
  • src/main/ipc/repos/repo-clone-lifecycle.ts
  • src/main/ipc/repos/repo-creation-handlers.ts
  • src/main/ipc/worktree-metadata-merge.ts
  • src/main/ipc/worktrees/listing/detected-worktree-scan-cache.ts
  • src/main/ipc/worktrees/listing/ssh-worktree-fallback.ts
  • src/main/project-realpath-identity.ts
  • src/main/runtime/orca-runtime-core.ts
  • src/main/runtime/repo-worktree-resolution-scan.ts
  • src/main/runtime/repo-worktree-row-resolution.ts
  • src/main/runtime/runtime-managed-worktree-queries.ts
  • src/main/runtime/runtime-nested-repo-import.ts
  • src/main/runtime/runtime-repository-clone-controller.ts
  • src/main/runtime/runtime-repository-registration-controller.ts
  • src/main/runtime/workspaces/workspace-catalog.ts
  • src/main/runtime/workspaces/workspace-repo-scan-refresh.ts
  • src/shared/worktree/ownership.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.

Walkthrough

Repository creation, cloning, and nested-repository imports now use Git-root or real-path matching to recognize local repositories reached through aliases. Worktree scans derive checkout roots and preserve selected-checkout identity in detected rows and timeout fallbacks. Integration tests cover alias paths, WSL matching, stalled scans, cached rows, and related repository operations.

Merge Risk: Low · previous review b3a81

Create, Clone, or nested import may remain pending while a disconnected project path is checked. This is a bounded-scope risk that can be accepted with owner awareness.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 41.18% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title "Keep a project's own checkout visible through path aliases" matches the main change: Git projects created or cloned through symlinked paths hid their own main checkout. The summaries show r…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description check Passed The description is complete and relevant. It explains the problem, user-visible changes, implementation, testing coverage, platform considerations, performance boundaries, and links issue STA-13215. I…
Full details: Title check

Explanation

The title "Keep a project's own checkout visible through path aliases" matches the main change: Git projects created or cloned through symlinked paths hid their own main checkout. The summaries show root derivation, real-path matching, and checkout marking across create, clone, and worktree listing, all aimed at keeping that checkout visible. The title is specific and omits only secondary details such as WSL skipping and the new test suites.

Full details: Description check

Explanation

The description is complete and relevant. It explains the problem, user-visible changes, implementation, testing coverage, platform considerations, performance boundaries, and links issue STA-13215. It does not use every template heading, and it omits an explicit risk level and visual-proof statement, but the required information is substantially covered.

Full details: Docstring Coverage

Explanation

Docstring coverage is 41.18% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 17 functions across 19 files.

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches
Generate docstrings
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

…classification

Resolve a saved project root asynchronously with each worktree scan and
carry the result with that scan's rows in memory, so visibility checks on
cached rows (lists, sidebar, process and file targets) touch no filesystem.
The registered checkout is recognized even when it is a linked worktree or
a stalled-scan metadata row. Nested repo import and the same-checkout
lookup recognize alias spellings without probing other WSL distros.
@brennanb2025

brennanb2025 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

Review status

The problem. If you created or cloned a Git project inside a folder reached through a symlink (~/code pointing at another disk, macOS /tmp, a Windows junction), the project showed up with no workspace. Orca saved the path as typed, Git reported the checkout at its real location, a plain-text comparison decided the checkout belonged to another project, and the default "hide external worktrees" setting hid it.

What changes for users. New projects from Create and Clone (desktop and paired host) save the location Git reports, like Add Project, so the checkout is visible right away. Projects already saved through a symlink, including ones registered at a linked worktree, show their own checkout again with no saved data rewritten. Repeating Create, Clone or nested import through the symlinked path finds the existing project. Other projects' worktrees stay hidden.

What review changed. The first version resolved the folder's real location synchronously on every visibility check, including checks on cached rows. A hung network mount could then have frozen the app. The fix was reworked so each worktree scan resolves the location once, in the background, and visibility checks never touch the disk. That pass also fixed three more cases:

  • projects registered at a linked worktree;
  • rows shown during a slow scan;
  • nested import making duplicates.

Creating a project also no longer touches unrelated WSL distros.

Verified.

  • Tests run against real Git and real symlinks. They cover Create, Clone, repeat requests, saved projects (IDs and details unchanged), linked worktrees, slow scans, retargeted symlinks, nested import and WSL/SSH isolation.
  • Contract tests bound the work: one resolution per project per scan at 3 and 30 projects, and no disk access on cached checks at 10 and 100 worktrees.
  • CI on 3a24ce1: "Mobile verify" fails in hermes-array-sorting-compat.test.ts on src/shared/plugins/approval/plugin-consent-fingerprint.ts. That file came from main (feat(plugins): commands[].replaces lets a mod take over a built-in action #37316), this PR doesn't touch it, and main's own Mobile Checks fail the same way (runs 41400828602 and 41402094836). Main's fix is open as fix(plugins): keep the plugin consent fingerprint Hermes-compatible so main's Mobile checks pass #37370. When the watcher stopped at that failure, 13 checks had passed and 18 were still running. On the previous head (fae6874), static analysis, typecheck and every unit shard passed except two tests that also failed on main.
  • QA evidence: src/main/ipc/repos-symlink-checkout.test.ts ran on a real Windows machine through the QA queue (Git for Windows 2.55, Node 24, real directory junctions; no app launch or agents). On the first try 7 tests failed, only because the tests spelled paths with backslashes; after the test fix, 12 passed and the macOS-only case was skipped at b3a8137. Logs are kept with the review notes.
  • After that run, 708a4e9 moved the in-memory checkout marker into a module the web typecheck can compile, with no behavior change (covered by the same test file, worktree-metadata-merge.test.ts and CI typecheck). The branch then merged main three times, each for main's own CI fixes: 62d51f3, fae6874, and 3a24ce1, which brings in Restore main unit checks for plugin routing and prompt receipts #37345. None of them touches this PR's files or anything this mechanism imports. On 3a24ce1 the PR's test files and the related creation, clone, registration, runtime-query, metadata-merge and folder-upgrade suites ran on macOS: 7 files, 118 tests passed. Local typecheck and lint weren't run; CI covers them.

Not verified. No running app was launched: nothing on screen changed, and the behavior is main-process logic covered by the integration tests above.

Deferred.

  • After a symlink is retargeted between two checkouts of the same repository, a paired host can keep the earlier checkout selected for up to its existing five-minute refresh window.
  • A mapped drive plus a junction on Windows may stay hidden, as it does today.

Already on main, not changed by this PR (for Brennan):

  • For projects saved through a symlink before this change, features that look up the project's main workspace by its saved path still miss it: fork sync, composer attachment targets, session-search scope. New projects don't have this.
  • Nested import through a symlinked folder still saves the typed spelling for newly imported projects, and doesn't fold a linked worktree into its project.

For Brennan's review

@brennanb2025

Copy link
Copy Markdown
Contributor Author

Closing in favor of #38208, which already registers Git's real checkout path for Create and Clone and dedups symlink aliases. The remaining older-alias listing change here conflicts with #38208's decision to keep main's fallback for older saved aliases.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant