Workspace Worktrees

Switch between tickets that span several Git repositories. Open the matching worktrees together in a new workspace window, with the remaining projects linked at their current paths. You can also switch an individual repository's worktree inside the current workspace.

The extension adds native Tickets, Worktrees, and Branch Comparison views to the Source Control sidebar:

SOURCE CONTROL
  ▾ TICKETS                               ↻
    ▾ SSPAS-1307                 2 projects  ⇄
        auth          SSPAS-1307-flyway-auth
        pin-center    feature/SSPAS-1307-flyway-pin-center
    ▸ SSPAS-1400                 2 projects  ⇄
  ▾ WORKTREES                              ↻
    ▾ auth                     feature/login
        main                      Clean    ⇄
      ✓ feature/login             Active · 2 changed
        fix/device-trust          Clean    ⇄
    ▾ pin-center                        main
      ✓ main                      Active · Clean
        feature/pin               Clean    ⇄

Click a ticket name to open its workspace. In the Worktrees view, hover over a worktree and click Switch Worktree to replace only that repository's workspace folder, preserving its display name and position. Selecting a worktree row alone does not switch anything.

With one project open, Tickets shows expanded ticket groups containing that project. Click the project row to open its matching worktree as a folder in a new window. This works with File → Open Folder… and saved workspaces containing one project, without creating ticket workspace files.

TICKETS
  ▾ SSPAS-1307                  1 project
      auth          SSPAS-1307-flyway-auth   ← click to open in a new window

If several worktrees match the same ticket, choose one in the picker; the choice is remembered. The new window uses the worktree's folder settings. Repository subfolders open at the corresponding subfolder in the target worktree. Branches without a ticket ID or configured prefix remain available in Worktrees.

Install

Requires VS Code 1.96 or newer, Git 2.31 or newer, and a trusted workspace. Git must be available on the machine where the workspace lives.

1. Download the VSIX from a successful repository Actions run, or build it using the instructions below.
2. In VS Code, open Extensions → … → Install from VSIX… and select workspace-worktrees-0.4.0.vsix.
3. Open Source Control → Tickets or Worktrees. If a view is hidden, use View: Open View….

You can also run:

code --install-extension artifacts/workspace-worktrees-0.4.0.vsix

You can also install Workspace Worktrees from the Visual Studio Marketplace.

Set up your workspace

Add each repository as its own folder with File → Add Folder to Workspace…, then use File → Save Workspace As…. A .code-workspace file can contain just one repository, too.

{
  "folders": [
    { "name": "auth", "path": "../auth/main" },
    { "name": "pin-center", "path": "../pin-center/main" }
  ]
}

Switching auth to feature/login updates only its folder entry. The pin-center folder and workspace-level settings remain intact. Git branches, files, indexes, and worktree registrations are not modified by the switch.

To replace a worktree inside the current window after opening a single directory, the extension offers Save Workspace As… first. Run the switch again after saving. Opening a project from Tickets works directly and always uses a new window. Untitled multi-folder workspaces also work; save them to keep your folder choices between sessions.

Repositories nested under a parent workspace folder are listed when VS Code's Git extension detects them. They must be added as separate, non-overlapping workspace folders to switch independently. Remove the encompassing parent folder from the workspace after adding its individual repositories. Workspace folders that point to a repository subdirectory are supported if the same subdirectory exists in the target worktree.

Switch tickets

For tickets spanning multiple projects:

1. Save your original workspace with one folder per repository, for example auth, pin-center, and gateway.
2. Create worktrees using Git or your agent. Branches such as SSPAS-1307-flyway-auth and feature/SSPAS-1307-flyway-pin-center automatically belong to SSPAS-1307.
3. Click SSPAS-1307 under Source Control → Tickets, or use Tickets: Switch Ticket in the Command Palette.
4. A new window opens SSPAS-1307.code-workspace, containing the matching Auth and PIN worktrees. Gateway and other unmatched workspace folders remain linked at their current paths, in their original order.

The original window and workspace file stay intact. These are references to existing folders: no projects are copied. Edits in an unmatched project are visible in every window that uses that same folder. Set workspaceWorktrees.ticketUnmatchedProjects to omit if you prefer a workspace containing only matching projects.

If one repository has several worktrees for the same ticket, a picker lets you choose. That choice is remembered for this ticket and original workspace. To change it, right-click the ticket and choose Choose Worktrees for Ticket…. Missing worktrees and invalid selections produce an error before a workspace opens.

Each original workspace has a separate catalog under the extension's global storage, in ticket-workspaces/<workspace-id>/. Each ticket reuses its own .code-workspace file there, allowing VS Code to restore that ticket's editor session. The original workspace's settings, launch configurations, tasks, extensions, and comments are copied on first creation. Subsequent opens update only the generated folder list, preserving ticket-specific settings and comments. Settings that contain paths relative to the workspace file itself may need adjustment because the generated file lives in a different directory; prefer ${workspaceFolder:project-name} in tasks and launch configurations.

The Tickets view remembers the original repository catalog, so other tickets remain available even when their projects are omitted from the current window. Use Tickets: Return to Original Workspace to reopen the source in the current window. Add repositories or change prefix rules there, then open a ticket to update the catalog. The catalog belongs to that original workspace; moving or copying generated workspace files outside extension storage does not preserve this association.

Ticket IDs are case-insensitive, start at a slash-separated branch segment, and have a project key followed by digits, such as ABC-42 or SSPAS-1307. For named initiatives, configure literal prefixes in the original workspace:

"workspaceWorktrees.ticketPrefixes": ["flyway", "checkout-redesign"]

This also groups feature/flyway-auth with fix/flyway-pin-center. Custom prefixes take priority over automatic ticket IDs; the longest matching prefix wins. No regular expressions are executed from settings.

Compare with a branch

Hover over a ticket or one of its projects in Tickets:

• Compare with Main (diff icon) opens a changed-files tree immediately. It tries local main, then origin/main, local master, and origin/master.
• Compare with Branch… (compare icon) opens a searchable picker of local and remote-tracking branches. For a whole ticket, the picker offers branches shared by every matching project. Compare individual projects when their base branch names differ.

The Branch Comparison view groups changed files by project and folder, with file counts and added/modified/deleted/renamed indicators. Click a file to open its side-by-side diff. Open All Changes in the view toolbar opens the full set in VS Code's multi-file diff editor. Change Comparison Branch… selects another baseline for the same projects; Refresh Comparison rebuilds the changed-file list after edits or Git operations.

BRANCH COMPARISON                       ≋  ⇄  ↻
  SSPAS-1307: main ↔ Working Tree · 4 changed files
  ▾ auth                        4 files · main ↔ SSPAS-1307-flyway-auth working tree
    ▾ src/main                  3 files
      ▾ java/config             2 files
          AuthDbConfig.java     Modified
          FlywayProperties.java Added
      ▸ resources               1 file
    pom.xml                     Modified

Comparisons use the selected branch's current local commit against the ticket worktree's current files. This includes committed differences, staged and unstaged changes, non-ignored untracked files, and unsaved buffers for open existing text files. It is a direct branch-to-working-tree comparison; changes made on the base branch after the ticket diverged also appear. Remote-tracking references use the last fetched state; comparing does not fetch.

The left side is an immutable, read-only Git revision. Normal working files on the right remain editable, and existing unsaved text is shown without saving it. Comparing leaves workspace folders, branch checkout, and the index unchanged. Binary contents are preserved, with rendering subject to VS Code's binary/image diff support; Git blobs larger than 16 MiB hit the extension's existing output limit and report an error. Symlinks show their link text, and submodules show commit/dirty-state summaries.

If several worktrees match a project's ticket, comparison uses the matching worktree already open in the workspace, then the remembered ticket choice, or asks you to choose. A ticket-level comparison covers that ticket's matching projects; unmatched linked projects remain available in the workspace.

Features

• Compare ticket worktrees with main or another branch, browse a project/folder tree of changed files, and open individual or multi-file diffs.
• Ticket grouping across repositories, stable generated workspaces, and remembered choices when branches share a ticket.
• Single-project ticket groups with clickable project rows that open worktree folders directly in a new window.
• Repository grouping by shared Git directory, including worktrees outside the workspace.
• Active branch, primary worktree details, detached HEAD, locks, missing directories, and stale registrations.
• Explicit switch buttons, context-menu actions, and a searchable Worktrees: Switch Worktree picker.
• Worktrees: Switch to Previous Worktree history saved per workspace.
• Changed-file and conflict counts loaded when a repository is expanded.
• Refresh from Git events, workspace changes, window focus, or the toolbar; periodic refresh while the view is visible and the window focused.
• Open Terminal and Copy Worktree Path from worktree context menus.
• Bounded Git concurrency, command timeouts, and isolated errors for individual repositories.
• All runtime code is bundled; no telemetry, network calls, or GitHub credentials are required by the extension.

Editors and running processes

Opening a ticket uses VS Code's workspace-opening behavior and separate editor sessions. In the default new-window mode, documents and processes in the original window stay there. Changing workspaceWorktrees.ticketOpenMode to currentWindow lets VS Code handle unsaved buffers and window shutdown as it would when opening any other workspace. Unsaved edits to the original or generated .code-workspace file must be saved first.

Before switching an individual worktree, affected unsaved documents require Save and Switch or cancellation. Saving writes to the original worktree. Changes are never copied into the selected worktree.

By default, ordinary text tabs with matching files reopen in the selected worktree, in the same editor groups. Visible cursor positions and selections are restored. Tabs with no matching target file remain open at their original paths. Sticky tabs, diff editors, notebooks, and custom editors also stay associated with their original resources. Set workspaceWorktrees.restoreEditors to false to keep all existing tabs at their original paths.

Replacing the first workspace folder can restart VS Code's extension host. The switch is recorded before replacement so editor restoration can continue after that restart. VS Code keeps the window open, but language services and other extensions may reinitialize.

Terminals, tasks, debug sessions, and running processes retain their original directories. Use Open Terminal on the selected worktree to start a terminal there. Folder-specific .vscode settings and tasks come from the selected worktree; workspace-level settings stay in the workspace file.

Settings

The extension follows the built-in Git extension's repository discovery. If Git is disabled, direct workspace folders can still be discovered using git from PATH. Linked-worktree listing is independent of git.detectWorktrees and its limit. Native Source Control may continue to display additional worktrees according to your Git settings; the Active marker here describes the current workspace folders.

In Remote SSH, WSL, and Dev Containers, install the extension in the remote workspace. Git and all worktree paths must be available in that same remote environment. Browser-only and virtual workspaces are unsupported.

Development

Use Node.js 24 and npm. All development dependencies are pinned in package-lock.json.

npm ci
npm run check
npm test
npm run test:integration
npm run package

Press F5 to launch an Extension Development Host. Packaging writes artifacts/workspace-worktrees-0.4.0.vsix and includes only the bundled extension, manifest, icon, README, changelog, license, and third-party notices.

Integration tests create disposable Git repositories and launch an isolated VS Code profile. They do not use your normal settings or extensions. On macOS they use the installed VS Code by default; elsewhere the test runner downloads stable VS Code. Set VSCODE_EXECUTABLE_PATH to use a specific executable, or VSCODE_VERSION to download a specific version. On headless Linux, run xvfb-run -a npm run test:integration. Set KEEP_TEST_FIXTURE=1 to retain the fixture and logs after a failure.

The ticket test generates workspaces, verifies unmatched-project links and settings preservation, then starts a second VS Code process in a generated workspace to check catalog restoration and selection of a ticket with different projects. Use WORKTREES_TEST_ONLY=tickets to run that scenario alone.

CI runs unit/Git tests on Linux, macOS, and Windows, and extension-host tests on Linux against the minimum supported VS Code version and stable. The stable integration job packages and uploads a VSIX artifact.

See architecture and maintenance notes for the switch lifecycle and validation boundaries.

Troubleshooting

• No repositories: open a Git workspace folder, or check VS Code's Git discovery settings for nested repositories.
• No tickets: save the workspace, ensure matching branches have registered worktrees, and check your prefix settings in the original workspace.
• Several folders from one repository: ticket generation currently requires one folder per repository. Individual worktree switching supports choosing among multiple folder bindings.
• Cannot switch a nested repository: make it a separate workspace folder and remove overlapping parent roots from the workspace.
• Missing worktree: repair or remove the registration using Git, then refresh. This extension never prunes or deletes worktrees.
• Git error: run Worktrees: Show Logs. Git safe-directory errors and missing executables are reported without silently changing Git configuration.
• Tabs still show the previous worktree: files missing in the target and specialized editors are deliberately retained at their original paths. Use the Explorer for the selected worktree.

Worktree creation, removal, branch checkout, and automatic process migration are outside the extension's scope.

License

MIT.