Multi-Repo Branch Switcher

Keep every Git repository in a VS Code workspace on the right branch—without switching them one by one.

Multi-Repo Branch Switcher coordinates branch checkout, creation, fallback, refresh, and cleanup across every Git repository detected by VS Code. It stays fast in large workspaces through cached refs and bounded concurrency, while making partial availability and unsafe repositories visible before they surprise you.

👁️‍🗨️ At a glance

🚀 Quick start

1. Open a VS Code workspace containing multiple Git repositories.
2. Open the Command Palette with Ctrl+Shift+P / F1, or Cmd+Shift+P on macOS.
3. Run Multi-Repo Branch Switcher: Switch Branches.
4. Review branch coverage and choose an existing branch—or select Create New Branches for All Repos.

💡 Tip: The first lookup populates the workspace cache and shows its progress as a cancellable notification. Reopening the picker is normally immediate within the set cache refresh window (default: 1h); Refresh Branch List forces a ref refresh when you need it.

👀 See it in action

Know where a branch exists

Each branch shows how many repositories have it locally or as an origin/* remote-tracking ref. Repositories that need fallback handling appear on the detail line, and both descriptions and details are searchable.

Stay concise, then drill down

Completion notifications summarize succeeded, skipped, and failed repositories. Select Show Details to open a copy-friendly report with one repository per line.

🧭 Commands

🔀 How switching works

For each repository, the extension evaluates the requested branch independently:

⚠️ Multi-repository checkout is not transactional. A repository can still change or fail while operations are running. Enable preflight for an explicit plan, and review skipped or failed repositories through Show Details.

Optional preflight

Preflight is disabled by default. When enabled, it:

• Plans every local checkout, remote tracking branch, creation, fallback, and blocked repository.
• Requires confirmation before any repository is changed.
• Rechecks repository safety after confirmation to catch last-second working-tree changes.
• Refuses to start when no repository can safely switch.

"multiRepoBranchSwitcher.preflight.enabled": true

Successful-switch follow-ups

When every repository succeeds, the extension can pull updates and reload the VS Code window. Both behaviors support Always, Ask, and Never. If any repository is skipped or fails, these follow-up actions do not run.

⚡ Cache and remote refresh

The branch picker reads local branches and locally available origin/* remote-tracking refs through VS Code's Git API. Those remote-tracking refs only change after a fetch.

• Cache entries are scoped to the current workspace and require a full rebuild on picker open after 3,600 seconds (one hour) without a successful refresh.
• Background refresh runs every 300 seconds after the previous run completes, starting after workspace startup. It fetches origin and updates the cache without opening the picker. Set cache.backgroundRefreshIntervalSeconds to 0 to disable it; disabling the cache also stops background work. Settings changes apply without reloading: those two settings reschedule immediately without interrupting a run already under way, and the rest take effect on the next run. Background failures are logged in the Background Refresh output channel, kept separate from switch results so they survive the next switch, and retried on the next interval; an ongoing failure is logged once when it appears and once when it recovers.
• Ref collection and repository processing use a configurable concurrency limit.
• If a local ref refresh fails, the last cached snapshot remains available and is marked stale.
• If fetching origin fails, locally available refs remain usable and the affected repository is reported.
• Manual refresh always rebuilds local refs and follows the configured remote policy.

Remote refresh policies

🧹 Stale branch cleanup

Run Multi-Repo Branch Switcher: Delete Stale Local Branches to clean up branches older than the configured cutoff.

• Protected patterns such as main, master, and develop are never deleted.
• The currently checked-out branch is always preserved.
• Repositories with working-tree changes, unpushed commits, or no upstream are skipped.
• Dry-run mode previews the result without deleting anything.
• Detailed results are written to the VS Code Output panel.

⚙️ Configuration

Open Settings → Extensions → Multi-Repo Branch Switcher, or add settings directly to settings.json:

{
  "multiRepoBranchSwitcher.defaultBranchName": "master",
  "multiRepoBranchSwitcher.registerChangesDelay": 1500,
  "multiRepoBranchSwitcher.autoPullBranchUpdates": "Ask",
  "multiRepoBranchSwitcher.autoReloadWindow": "Ask",

  "multiRepoBranchSwitcher.cache.enabled": true,
  "multiRepoBranchSwitcher.cache.ttlSeconds": 3600,
  "multiRepoBranchSwitcher.cache.backgroundRefreshIntervalSeconds": 300,
  "multiRepoBranchSwitcher.remoteRefresh.policy": "When Cache Expires",
  "multiRepoBranchSwitcher.maxConcurrentRepositories": 4,
  "multiRepoBranchSwitcher.preflight.enabled": false,

  "multiRepoBranchSwitcher.prune.cutoffDays": 14,
  "multiRepoBranchSwitcher.prune.protected": ["^(main|master|develop)$"],
  "multiRepoBranchSwitcher.prune.dryRun": false
}

All setting names are prefixed with multiRepoBranchSwitcher..

📦 Installation

Visual Studio Marketplace

1. Open the Extensions view in VS Code.
2. Search for Multi-Repo Branch Switcher.
3. Select Install.

Open Multi-Repo Branch Switcher in the Marketplace

Manual VSIX installation

1. Download the latest .vsix from GitHub Releases.
2. In the Extensions view, open More Actions….
3. Select Install from VSIX… and choose the downloaded file.

Requirements

• VS Code 1.99.0 or newer.
• Git repositories must be detected by VS Code's built-in Git extension.

💬 Feedback and contributing

Bug reports, feature ideas, and pull requests are welcome in the GitHub repository. Please include relevant repository states and extension settings when reporting branch-switching behavior.

Released under the MIT License.