GitHub (VSCode extension — proof of concept)

A GitHub companion for VSCode. Browse and manage your repositories across every signed-in gh account and org from a dedicated GitHub view, with a status-bar surface for your accounts and sync state. One of its core features is a first-class git worktree workflow for the bare-repo layout:

~/Repos/host/owner/repo/        ← container (holds .bare + flat worktrees)
├── .bare/                      ← bare clone
├── .git                        ← "gitdir: ./.bare"
├── main/                       ← worktree  (flat sibling)
└── feature-login/              ← worktree  (flat slug of "feature/login")

Worktrees are created as flat siblings of .bare; branch slashes are slugified (feature/login → feature-login). Each worktree is added to the workspace as its own root, labelled repo/branch (configurable depth) so you can tell repo and branch apart in the Explorer.

Features

• Repository management — list, clone, and open repos across accounts/orgs from the GitHub tree view.
• Worktree workflow — bare-repo layout with flat sibling worktrees and repo+branch identity.
• Autosync — keep clones and branches reconciled with the remote on a configurable cadence.
• Accounts status bar — the GitHub glyph with a cached, auto-refreshing account overview.

Built for VSCode 1.120+ (tested on 1.123), git 2.50; distributed as a local .vsix (no marketplace).

Run it (Extension Development Host)

npm install
npm run compile        # or: npm run watch

Then open this folder in VSCode and press F5 ("Run Extension"). A second VSCode window launches with the extension loaded.

Make a test repo

./scripts/make-demo-repo.sh           # creates ~/wt-demo/...
# Open the printed worktree folder (…/cool-repo/main) in the dev-host window

Try the features

In the Extension Development Host, with a worktree folder open:

• One file UI: every opened worktree/repo is a root in the multi-root Explorer. Git working-tree roots are auto-labelled with parent path segments (msx.github.label.parentDepth, e.g. repo/branch); the bare container (the folder holding .bare + the .git pointer) keeps its plain folder name, since its worktrees are already visible inside it.
• Source Control view shows all repositories side by side — worktree-based and ordinary single-branch repos — in the built-in Repositories list.
• Create a worktree like creating a branch: the New Worktree button in the Source Control view title. Type a name → branch + worktree + added to the workspace, in one step.
• Source Control view → ··· overflow → Worktrees ▸ — the full worktree menu.
• File Explorer → right-click → Worktrees ▸ — same menu from the Explorer.
• Right-click a repository in the SCM Repositories view → Open Branch as Worktree…
• Command palette → Worktrees: — all commands.

GitHub view

A dedicated GitHub activity-bar view browses everything reachable through your gh CLI logins and clones it straight into the worktree layout. It mirrors the bulk PowerShell sync (Checkout-GitHubRepo.ps1), but lazily and on demand:

github.com                       (host — desc: account login)
  MariusStorhaug  ‹you›          (personal owner)
    PowerShell      master  ● cloned
      master        ✓ worktree
      feature/new   ✓ worktree  local
      feature/…
    PSModule …                   (orgs)

• Host → Owner → Repo → Branch, spanning every authenticated host (gh auth status). Owners are your personal account(s) (tagged ‹you›) plus their orgs (gh api user/orgs). Authentication and the multi-account model are specified in docs/auth.md.
• Lazy: orgs+repos load when a host/owner is expanded; branches (gh api repos/{owner}/{repo}/branches) load only when a repo is expanded.
• Local-state decorations: cloned repos show ● cloned; branches checked out as worktrees show ✓ worktree; a locally-created branch not yet pushed to the remote also shows local; the default branch is marked.
• Everything is cached in-memory; the title-bar Refresh (and the inline refresh button on every host/owner/repo row) clears the matching cache and re-queries gh, then recursively warms that subtree (hosts → owners → repos → branches) so collapsed levels expand instantly. The walk runs with bounded concurrency behind subtle status-bar progress and is cancellable; hidden/disowned scopes are skipped.

Actions (right-click menu + inline eye)

Clones use the HTTPS URL (https://<host>/<owner>/<repo>.git) so they ride your existing gh credential/SSO sessions. Routine, hands-off cloning is driven by the cloneNew capability (enable it on a scope via right-click Maintenance ▸); the explicit Clone All Branches (repo) and Clone into Worktree (branch) buttons cover the on-demand case regardless of capabilities.

Autosync

Each scope (host / owner / repo / worktree) carries a set of maintenance capabilities — small, independently-togglable switches that each enable exactly one reconcile behaviour. Capabilities are tri-state (on / off / inherit) and cascade down the hierarchy. Every capability's global default is off: a fresh install does nothing — no fetch, no clone, no delete — until you enable a capability at some scope. The full model (exact semantics, inheritance, the reconcile algorithm, the safety envelope) is specified in docs/modes.md; this is the overview.

Capabilities are reconciled against gh/git on Refresh, on Sync Now, and on a background schedule (autoSync.intervalMinutes, default 5 min; autoSync.fetchIntervalMinutes, default 15, throttles the per-repo network fetch). Set them per node from the view: right-click a host/owner/repo/worktree row → Maintenance ▸, then toggle each capability (Inherit · On · Off) or apply a Preset (Mirror · Fresh, never delete · Disown (Ignore) · Reset all). The title bar has Sync Now ($(cloud-download)), Refresh, and Add Repos Root to Workspace / Open Repos Root in New Window (which open the whole reposRoot as a plain folder, no cloning); its … overflow toggles Hide / Show Hidden Sections (hidden sections are hidden by default), Show / Hide Eye Icon (msx.github.showEyeIcon), and Show / Hide Add to Workspace Icon / Show / Hide Open in New Window Icon (msx.github.showAddToWorkspaceIcon / msx.github.showOpenInNewWindowIcon). Every row shows a compact badge of its effective on capabilities (inherited ones parenthesised); a fully-disowned row shows ⊘ ignored.

Resolution is by nearest set scope: a repo inherits from its owner, an owner from its host, a host from the global msx.github.auto.<cap> default. An explicit child value always wins — including turning a capability back off under a scope that turned it on (tri-state is essential: off must be distinguishable from unset). The sub-choices cloneScope, pullScope, and pullSource resolve by the same walk, each from its own global default. Overrides and per-folder identity live in metadata.json files written at each level (<reposRoot>/, <host>/, <owner>/, <repo>/): a node's override sits in its parent's file (so it survives the node's own deletion), its identity in its own file. Config travels with the reposRoot tree and is human-inspectable.

Ignore & Remove local copy. Maintenance ▸ Disown (Ignore) stamps every capability to explicit off at the scope, fully disowning it and everything beneath from all inherited capabilities — the durable "stop managing this" barrier (it lives in the machine-local metadata store under the extension's global storage, not in the repos tree, so it survives a later folder deletion). Un-ignore clears the stamped entry back to inherit. The inline eye toggles a scope's hidden display flag (cosmetic — hide a row without changing whether it is managed), gated by msx.github.showEyeIcon. Remove local copy… is a separate, one-shot action that deletes a scope's managed folder from disk now; it is not a persistent capability. Disown + Remove local copy together = "stop managing this and delete the bytes."

Clone layout (repoLayout). Every clone path — cloneNew, the explicit clone actions, and on-demand Add to Workspace — respects the effective repoLayout for the repo (regular | worktree, resolved by nearest-set-ancestor from msx.github.repoLayout, default regular). regular produces a plain git clone with one working directory; worktree produces the bare+worktrees container. Override per host/owner/repo via Maintenance ▸ Layout ▸. See docs/repo-layout.md for the full resolution rules and capability interactions.

Clone scope decides how much cloneNew checks out: bare (only .bare + the .git pointer), default (one worktree for the default branch), or all (a worktree per remote branch). It resolves by nearest set scope exactly like a capability — repo → owner → host → the global msx.github.cloneScope default — and is stored in the same metadata.json child entry. Every clone path honours the effective scope — the manual Clone / Clone All / Clone Repository (Worktree Layout) actions and cloneNew clone-adds — so e.g. a host with cloneNew on at bare scope stages its repos as bare containers in the background, while a single repo at all keeps every remote branch checked out.

What deleteAbsent removes, scoped to where it's set:

• host = deleteAbsent → owner folders under …/<host>/ no longer in your authoritative org list (you left/lost the org).
• owner = deleteAbsent → repo containers under …/<host>/<owner>/ no longer present remotely (repo deleted/renamed).
• Worktree removal (an upstream-[gone] or merged branch) is pruneBranches/pruneMerged, not deleteAbsent.

Safety model: publish, don't withhold

Safety comes from getting your work onto the remote, not from refusing to clean up:

1. Publish ASAP. Every branch the extension creates/opens is pushed with git push -u origin <branch> immediately (gated by autoSync.publishNewBranches, default on). Each reconcile re-publishes managed branches that still lack an upstream (e.g. an earlier offline push). Committed work therefore lives on the remote, so cleanup is non-destructive to real work. Push failures are logged, never blocking. We never set tracking config without a successful push — doing so would point an upstream at a ref that doesn't exist remotely, which the prune logic would then read as [gone] and delete.
2. Stash scratch before removing. Before removing a stale worktree, any uncommitted changes are git stash push -u'd (gated by autoSync.stashBeforeDelete, default on). The stash lives in .bare, so it survives worktree removal and stays recoverable.

Deletion signals

• Branch/worktree cleanup uses remote-branch absence, not merge state. A reconcile runs git fetch --prune; a managed worktree whose branch had an upstream that is now [gone] is removed and its local branch deleted. This catches branches deleted after a squash merge (where git branch --merged would never list them). Branches with no upstream (never published / failed push) are never auto-deleted. The default branch is never removed. A failed fetch ⇒ no prune-deletes that cycle.
• Folder deletion uses authoritative gh listings. Driven only by a gh api --paginate call that exits 0 (HTTP 200, all pages fetched). Any page error ⇒ non-authoritative ⇒ zero folder deletes that cycle (clone-adds may still proceed). Only directories that are clearly ours (bare-repo containers; for owner folders, every child is one) are ever candidates.

Circuit breakers (for the destructive folder deletes)

• autoSync.maxDeletesPerRun (default 50): a scheduled run that would delete more folders than this skips all folder deletes and notifies. Branch-worktree pruning is not limited.
• A scheduled folder delete skips any container holding unpushed commits, unpublished branches, or uncommitted changes (logged). Sync Now (and whole-tree Refresh) instead opens a modal listing every path to delete — flagging the unsafe ones — and force-deletes on your confirmation. This is the explicit override, and it guards against an auth blip returning an authoritative-but-empty set.
• All destructive paths share one envelope. deleteAbsent, pruneBranches/pruneMerged, and the one-shot Remove local copy all funnel into the same queue + confirm / circuit-breaker / unsafe-skip envelope, so a disowned repo under an otherwise-managed owner is still removed by an explicit Remove local copy. A whole-host removal is never done on a schedule and, on Sync Now, requires typing the host name to confirm.

Notifications (msx.github.notify.*)

Autosync reconciles and tree-command outcomes flow through one configurable notifier: a button-less summary toast (collapsible, severity-routed) with a [Details] link that opens the full report. Tune it with notify.level (off / errors / changes / all), the per-category notify.events toggles, and notify.detailsSurface; notify.statusBarOnly mutes toasts entirely. The GitHub output channel is the always-on log regardless. See docs/notifications.md for the full design.

Settings (msx.github.*)

On-clone git configuration (git.*)

Every bare clone — the manual Clone (Worktree Layout), the GitHub view's Clone / Clone All, and autosync clone-adds — funnels through one path that, right after the initial fetch, applies a set of git defaults to the container's shared .bare/config (so every worktree inherits them). Each step is independently toggleable via msx.github.git.* and best-effort: a gh/network/scope failure is logged to the GitHub output channel and never fails the clone.

• Identity (git.setUserIdentity) — user.name/user.email from the owning gh account; skipped when no account resolves (e.g. a manual clone on a host you have no gh login for).
• pull.rebase (git.pullRebase) — default false; unset leaves git's own default.
• Origin refspec (git.originFetchRefspec) — set before the fetch so all remote branches mirror under refs/remotes/origin/* (required by the worktree layout).
• Default-branch tracking (git.setBranchUpstream) — branch.<default>.remote/merge, so the default worktree tracks origin/<default> (default resolved via git symbolic-ref --short HEAD, robust on a bare repo).
• Fork upstream (git.forkUpstream) — for repos gh reports as forks, add an upstream remote pointing at the parent (default full = parent clone URL + fetch refspec).
• Windows long paths (git.windowsLongPaths) — core.longpaths=true at --system scope (Windows only, once per session).

Applies at clone time only — existing clones aren't retroactively reconfigured. Turn the whole thing off with git.autoConfigure=false.

Known limitations

• SCM provider row label: the built-in git provider shows each repository by its on-disk folder basename (the branch slug). Repo identity is carried by the multi-root Explorer label (ends with repo/branch), not the SCM row.
• The bottom-bar branch glyph is owned by the built-in git extension and exposes no third-party menu point; worktree creation lives in the Source Control view's title button and repository-row menu instead.
• Re-labelling the first workspace root triggers a window reload (VSCode API behaviour).