Show worktrees in the repository sidebar

[ignatremizov]

Summary

Add an optional sidebar mode that shows linked worktrees nested under their repository in the main repository list.

This keeps repository switching fast for worktree-heavy workflows without forcing users through the worktree dropdown for every switch.

Changes

• add a secondary Appearance setting to show worktrees in the repository sidebar when worktree support is enabled
• group linked worktrees under their main repository in the sidebar
• synthesize child rows for linked worktrees discovered from git worktree list even when those worktrees were never added as repositories
• support linked-only setups by synthesizing sibling worktree rows even when the stored entry is itself a linked worktree instead of the main worktree
• use worktree folder names for child row labels while preserving existing alias styling for saved repository entries
• use the same displayed-title logic for sorting and disambiguation so nested rows sort and label consistently with what the user sees
• preload main-repository worktree state for the sidebar so nested rows and stored linked-worktree branch pills are available on initial render instead of only after opening the worktree dropdown or forcing another sidebar refresh
• refresh parent sidebar rows when linked worktrees are selected so nested rows stay in sync with the active repository view
• let explicit parent-row clicks in the sidebar open the main worktree instead of restoring the last selected linked worktree from the preferred-worktree flow added in store last selected worktree, and open that when reselecting repo #106
• surface nested worktree rows from both saved worktree repositories and synthetic virtual rows without duplicating entries already stored in Desktop
• avoid duplicate Pull all work for linked worktrees while still including orphan linked worktrees when the main repo is absent from the stored repository list
• route virtual worktree open failures through the normal app error path instead of silently failing
• open synthetic worktree rows transiently instead of persisting them as top-level repositories under Other
• keep linked worktree rows as leaf nodes in the sidebar, regardless of whether they come from saved repositories or synthetic worktree discovery
• replace Remove… with Delete… for linked worktree rows and make deleting a saved linked worktree remove both the Desktop repository entry and the on-disk worktree/Git worktree metadata
• remove group-name actions from saved linked worktree rows while keeping alias support for explicitly-added saved worktrees
• inherit the main repository's GitHub association when a known linked worktree is added through Add local repository, so saved worktrees stay grouped under the main repo instead of moving to Other
• ignore stash-metric persistence for transient synthetic rows so sidebar-only worktree selection does not try to look up non-persisted repositories in repositories-store
• keep transient synthetic worktree selections stable across repository-store refreshes so switching to a worktree from another repository family does not snap back to the previously selected saved repository
• add stale worktree affordances in the sidebar with a warning icon, clearer tooltip text, click suppression, and a context-menu action that prunes stale worktree metadata for the repository
• avoid an empty leading context-menu section for virtual rows by only rendering the alias/group separator when those actions are present
• make the Add local repository dialog submission reliable for linked worktree paths by resolving the submitted path consistently and waiting for picker-selected paths to land in component state before submit runs
• persist sidebar worktree metadata in repository state and extract the sidebar-specific state shaping into a dedicated helper to keep app-store.ts smaller
• move the worktree-specific sidebar row construction into a dedicated helper so group-repositories.ts stays closer to upstream
• throttle sidebar worktree refreshes during repository indicator updates to reduce repeated git worktree list churn
• prune sidebar worktree refresh timestamps when repository lists change so stale cache entries do not accumulate
• tighten TypeScript null/undefined handling in repository and sidebar list code so production webpack builds pass across the full CI matrix
• add and extend unit coverage for grouped rows, synthetic rows, linked-only setups, stored linked-worktree branch labels, stale worktree rows, repository-list context menu behavior, and transient synthetic repository store behavior

Notes

This builds on the existing worktree support in #62, the toolbar hierarchy follow-up in #81, and the preferred-worktree persistence added in #106.

The feature stays behind a separate Appearance setting so users can keep the existing grouped-in-dropdown workflow if they prefer it.

The sidebar intentionally supports both kinds of linked worktrees:

• repositories that were already added to Desktop as standalone entries
• worktrees that only exist in Git metadata and were never added through Desktop

That second case is why the implementation includes synthetic child rows and startup/sidebar refresh state, rather than only changing the existing filter logic.

Because #106 persists the last selected worktree for a repository, this PR also makes explicit parent-row clicks in the sidebar opt out of that restore path so clicking the repository row still opens the main worktree directly.

Linked worktrees are now always treated as leaf nodes in the sidebar, even when they were explicitly added to Desktop as saved repositories. Only the main worktree row owns nested worktree children.

Saved linked worktrees still keep alias support, but group-name actions are removed for them to avoid implying that linked worktrees can act as group parents. Synthetic worktree alias support would require a separate metadata store keyed by worktree path, so that is left as possible follow-up work instead of extending the normal repository persistence model in this PR.

For stale worktrees, the new prune action is repository-scoped because it maps to git worktree prune, which removes any stale worktree metadata Git reports for that repository.

Testing

• yarn test:unit app/test/unit/repositories-list-grouping-test.ts
• yarn test:unit app/test/unit/repository-list-item-context-menu-test.ts
• yarn test:unit app/test/unit/repositories-store-test.ts
• yarn lint
• yarn compile:dev
• yarn compile:prod

Example

New setting if "show worktrees dropdown in toolbar" is ticked

Stale worktrees

[pol-rivero]

I think this is a much needed feature, but I'm not a big fan of the large diff in app-store.ts. Maybe you could have a look at this block:

const repositories = this.state.repositories.filter(
    r => !(r instanceof Repository && isLinkedWorktreeSync(r.path))
  )

This was added here: 546af41. Conditionally skipping this filter should be enough to show linked workspaces in the sidebar, I think.

[ignatremizov]

Sure, give me a day to take a look

This was mostly one-shot with codex, without the usual review hardening passes I do since I just wanted to get it working for myself

The issue with that filter is that worktrees could be created but not saved in Github Desktop, or already saved in Github Desktop via the "add local repository" action:

But the idea is to generate synthetic rows for the worktrees that don't exist as saved yet, while also handling the ones that are saved as "local repos"

the original implementation merged decided a dropdown table per "real" repo is better, and to hide any earlier repos which are themselves worktrees, while mine reverses that decision and renders the worktrees with synthetic repo rows

[pol-rivero]

The issue with that filter is that worktrees could be created but not saved in Github Desktop, or already saved in Github Desktop via the "add local repository" action.

Ah I see, that makes sense.

Edit: I've done an initial pass on your PR. While it's still bigger than I'd like, most of the complexity seems justified, I haven't found any good workaround to avoid creating those synthetic rows.
I've added some comments below to try and mitigate the large complexity slightly.

[ignatremizov]

Added:

• open synthetic worktree rows transiently instead of persisting them as top-level repositories under Other
• keep stored linked-worktree rows on the normal repository-management context menu while giving synthetic rows a worktree-specific context menu
• add stale worktree affordances in the sidebar with a warning icon, clearer tooltip text, click suppression, and a context-menu action that prunes stale worktree metadata for the repository
• avoid an empty leading context-menu section for virtual rows by only rendering the alias/group separator when those actions are present

[ignatremizov]

@pol-rivero check if anything else is missing or you want moved around

[pol-rivero]

Thanks for the update. I've done some more tests and found the following:

• While the context menu in the synthetic rows seems correct, the non-synthetic worktrees still show the old context menu (see comment).
• When clicking on a synthetic row, the repository seems to be in an inconsistent state with negative ids

---

Also, I'd appreciate it if you could do separate commits instead of just updating a single commit, this way I can see the actual changes between revisions.

[ignatremizov]

@pol-rivero I pushed a follow-up fix for the synthetic-row state issue.

Root cause was not the negative ids by themselves, but that synthetic sidebar-only worktree rows are transient Repository objects and are not persisted in repositories-store. Some stash-metric code still assumed every selected repository existed in that store, which is what caused the getLastStashCheckDate failure for the synthetic row.

I fixed that by treating transient synthetic rows as non-persisted in the stash-check tracking path, and added a regression test for it.

On the context menu behavior: I intentionally kept stored linked-worktree rows on the normal repository menu for now. My reasoning is that if a user explicitly added a worktree as a regular Desktop repository, they should still be able to use the normal repo actions there (alias, grouping, etc), especially Remove…, which updates Desktop’s stored repository list. Once that stored row is removed, the synthesized sidebar row becomes the representation for that worktree, and that row uses the worktree-specific context menu.

That keeps the behavior compatible with the base GitHub Desktop mental model instead of automatically "converting" stored repo rows to worktrees, or hiding them entirely.

If you’d prefer a different UX here, I can revisit that part separately, but I wanted to avoid implicitly changing persisted repo rows into a different interaction model, even if they are semantically worktrees.

[pol-rivero]

@ignatremizov It seems this is still under active development. Let me know once you have a definitive and completely tested version that I can review. :)

Due to the force-pushing, it's very exhausting to continue re-reviewing the same changes all the time.

[pol-rivero]

I did a quick test for the stash-check and it seems to be fixed. Nice job.

if a user explicitly added a worktree as a regular Desktop repository, they should still be able to use the normal repo actions there (alias, grouping, etc),

In that case, the alias functionality should be fixed, it seems to be broken for linked worktrees at the moment.
I think the grouping functionality should only be shown in the main worktree, because it breaks the worktrees grouping otherwise:

---

especially Remove…, which updates Desktop’s stored repository list

The "Delete worktree" dialog should also update the stored repository list. If it doesn't, let me know and I'll fix it, because that would be a bug.

I believe that treating linked worktrees as repositories should be an implementation detail, and users should not be aware of it. That's why the context menu on real or synthetic linked worktrees should be identical in my opinion.
Selecting "Remove..." on a linked worktree and being prompted to "Remove repository" seems unintuitive.

[ignatremizov]

@pol-rivero I pushed another follow-up based on your feedback.

Changes in this round:

• linked worktrees are now always treated as leaf rows in the sidebar
• only the main worktree can own/show nested worktree children
• saved linked worktrees no longer show group-name actions
• linked worktree rows now use Delete… instead of Remove…
• deleting a saved linked worktree now does both:
  • removes it from Desktop’s stored repository list
  • deletes the worktree itself from disk / Git worktree metadata
• saved linked worktrees now inherit the main repository’s GitHub association when added through “Add local repository”, so they stay grouped under the main repo instead of falling into Other
• synthetic linked-worktree selections are now kept stable across repository-store updates, so selecting a worktree from another repo family no longer snaps back to the previously selected saved repository
• the “Add local repository” dialog got two reliability fixes:
  • submit-time validation now resolves the path the same way as the live picker validation
  • picker-selected paths now finish landing in component state before submit runs

I agree for the behavior to be aligned more closely with “linked worktrees are an implementation detail” rather than a second repository model in the UI.

I kept alias support for saved linked worktrees for now. I did not add alias support for synthetic rows in this PR, because that would require introducing a separate store keyed by worktree path instead of relying on the normal repository persistence model.

My current thinking is that synthetic alias support is probably follow-up work if we still want it after merge. In practice, renaming the worktree folder itself already gives a reasonable alias-like result for synthetic rows, since those rows display the basename when no explicit alias exists. If it's still important, I’d prefer to handle that in a separate PR with a small dedicated metadata store rather than growing the repository persistence model further.

About the force-push: I had to rebase after #106 landed because this branch needed to opt explicit sidebar parent-row clicks out of the new "reopen last opened worktree" behavior.

[pol-rivero]

Phenomenal job! Let's get this merged into the main branch so I can start daily-driving it in search of bugs. :)
Feel free to submit follow-up PRs if you find errors or potential improvements.

In practice, renaming the worktree folder itself already gives a reasonable alias-like result for synthetic rows, since those rows display the basename when no explicit alias exists.

I completely agree, renaming a worktree is enough. That's why I originally proposed not showing the alias option in linked worktrees (synthetic or otherwise).
In fact, I'm still in favor of never showing this option in linked worktrees (even if non-synthetic ones technically support it), because the end user has no idea that some rows are synthetic, and it feels weird to have the option in some worktrees but not in others.

[pol-rivero]

This is now available in v3.5.8