BranchHarbor

Multi-repository Git worktrees. One workspace per feature.

BranchHarbor by Ameyon Labs Inc. turns a feature spanning several Git repositories into one saved VS Code multi-root workspace. Keep several features open in separate windows without switching the branches in your original checkouts.

Quick start

1. Open the Command Palette and run BranchHarbor: Add Repository. Select one or several existing local Git checkouts.
2. Mark repositories Common to preselect them for each feature, or Optional to pick them only when needed.
3. Run BranchHarbor: Create Feature. Enter a name, select repositories, choose the branch name, and choose a starting revision.
4. Review the plan and create. Choose Open in new window when ready.
5. Find saved features in the BranchHarbor section of Explorer. Open any feature in its own window, or remove its clean worktrees when finished.

The same branch name is used in each selected repository. New branches start at the revision you choose, resolved separately in each repository. Existing local branches are reused at their current tip only if not checked out elsewhere. An unavailable base or occupied branch stops creation before any worktree is created. Remote branches can be used as bases, but this extension never fetches.

Features

• A reusable repository catalog, with common and optional selections.
• A separate Git worktree for each repository in each feature.
• Saved .code-workspace files with relative folder paths and a feature window title.
• Reopen several features in parallel VS Code windows.
• Cross-window operation locking and an automatically refreshed feature list.
• Durable partial-failure records, cancellation between repositories, and safe cleanup.
• No runtime npm dependencies, telemetry, or extension account requirement.

Storage and settings

By default, worktrees and workspace files live in this extension's VS Code global storage, under workspaces/. Use Choose Worktree Storage Folder to select a more convenient folder outside your source repositories. This affects only new features. Existing features remain where they were created.

The local catalog is not included in Settings Sync. Each VS Code profile or remote extension host has its own catalog. This extension runs on the workspace host; when used through Remote SSH or a development container, select repositories accessible on that host. Browser-only VS Code and virtual filesystems are not supported. Git must be installed and available on PATH.

Generated workspaces set only the window title. Existing workspace settings, launch configurations, tasks, secrets, .env files, ignored files, dependency folders, and uncommitted changes are not copied. Repository-tracked .vscode files remain part of the normal checkout. Review repository tasks and trust only repositories you know.

Safety

• Original checkout branches and uncommitted files are left in place.
• No automatic reset, stash, force removal, branch deletion, pull, push, or install.
• Checkout hooks and Git filesystem-monitor hooks are disabled for managed Git commands.
• Source and linked-worktree registrations for the same Git repository are deduplicated.
• Removal checks every member for changed, untracked, and ignored files before removing any member. Git checks again without force when each worktree is removed.
• Removal also blocks assume-unchanged and skip-worktree index flags, which can hide local edits from Git status. Preserve those files and clear their flags manually.
• Detached-HEAD worktrees cannot be removed until you create a retaining local branch.
• Branches and commits remain after removal. Workspace files and extra files in the feature folder are also preserved because they may contain your edits.
• Close windows using a feature before removing it. Disk checks cannot detect unsaved editor buffers in other windows. Unsaved file buffers in the current window block removal.
• Stop background builds and other file writers before removal. Each worktree is rechecked immediately before removal, but filesystem checks and Git removal cannot be atomic with changes made by unrelated processes.
• No submodule initialization, Git LFS installation, sparse-checkout migration, or dependency bootstrapping is performed. Configure those manually if required.
• Git checkout can invoke content filters already configured on your machine (for example, an installed Git LFS filter). Those filters may run programs or use the network. Register only repositories and Git configuration you trust.

Interrupted creation

Completed worktrees remain on disk and the feature appears with an error status. Open the feature to inspect completed members, or remove its clean worktrees and create a fresh feature. No completed work is automatically rolled back. A failure in cleanup can leave some members removed; run cleanup again after addressing the reported blocker. Branches remain available throughout.

If VS Code is forcibly terminated during an operation, the operation lock can remain. First close every VS Code window using this extension. Then remove only the operation.lock file at the exact path shown in the error and reopen VS Code. Do not remove the catalog or worktree folders. The conservative lock deliberately does not guess whether a process is still working.

Commands

• Add Repository
• Manage Repositories
• Create Feature
• Open Feature in New Window
• Remove Feature Worktrees
• Choose Worktree Storage Folder
• Refresh Features

Development

Use Node.js 22 or newer, npm, Git, and VS Code 1.95 or newer.

npm ci --ignore-scripts
npm run check
npm test
npm run package

Press F5 to launch an isolated Extension Development Host. The integration tests use temporary real Git repositories to cover isolation, parallel features, branch collisions, dirty/ignored-file protection, cancellation, locking, and hook suppression. CI runs the same suite on Linux, macOS, and Windows.

Privacy and license

All catalog data remains on your machine or selected remote extension host. The extension itself makes no network requests and sends no telemetry. Your configured Git content filters operate independently, as described above. See the included LICENSE file for usage terms.

Product page · Privacy · License terms · Support