GitHub Worktree Utils
Batch Git worktree commands for a workspace of many repositories — create, update, repair and tear
down a feature across all of them from the Command Palette, instead of one repository at a time.
Summary
A developer working on one feature across thirty repositories does the same Git work thirty times:
create a worktree, fix the tracking branch, bring it up to date, and eventually clean it all up. This
extension does each of those once, for the repositories you pick, and tells you exactly what happened
in every one.
It replaces five shell scripts that were already in daily use, and keeps their guarantees. It was
built by the developers who use it every day, and it is here for anyone who works the same way.
Business Problem
One person now works on several things at once. Agents and modern tooling made that normal, and
the old habit — one branch per task, switched in place — did not survive it.
Switching a branch costs setup time, and worse, it breaks things that were working: uncommitted
state, project references, cross-repository references, and half-finished work that is hard to
recover and harder to maintain. Every switch is a small demolition of a working environment, and at
several tasks a day it stops being small.
Git worktrees solve that — a task gets its own directory, and nothing you do in one disturbs another.
The reason people do not use them is that creating them by hand across many repositories is the
whole problem again, one repository at a time.
This extension creates them in batch, across many repositories, with the least setup. So one
person can open several terminals or VS Code windows, each on one worktree with its repositories,
and work, prompt and fix bugs in parallel — without any of them breaking the others.
It also costs less to run. An instance scoped to one worktree and one task keeps its context on that
task, rather than on everything else in the tree.
| Problem |
What it costs without this |
| Setting up parallel work on several tasks |
Branch switching, and a working environment torn down and rebuilt each time |
| Creating a feature's worktrees |
The same four commands, repeated per repository |
| A branch tracking the wrong remote branch |
Pull requests full of unrelated commits, found late |
| Bringing a feature up to date |
Fetch and merge everywhere, including repositories nothing moved in |
| Cleaning up a finished feature |
Checking every repository by hand for unsaved or unpushed work |
| Knowing where you stand |
No single view — the answer is thirty git status runs |
The last row is the expensive one. Without a reliable overview, the safe move is to check everything,
so the cost of deciding becomes as high as the cost of doing.
Solution
Six commands, all under Git Utils in the Command Palette. Each one asks which
repositories to act on, does the work, and reports per repository.
| Command |
What it does |
| Show Branches |
A read-only board: branch, tracking, staleness, and the recommended next action |
| Create Worktree |
Creates a feature worktree in each selected repository, and copies shared files such as .env into it |
| Fix Upstream |
Repairs wrong or missing tracking branches, without pushing anything |
| Update Worktree |
Brings each branch up to date with its own remote, then merges the default branch in. Fetches only what you selected — never rebases |
| Cleanup Worktree |
Tears down a finished feature, refusing outright if anything would be lost |
| Remove Repos |
Removes some repositories from a feature; the feature folder survives |
How a run works
Every command follows the same six steps, which is why they behave predictably as a set.
The Observe step is the one that matters most: the tool never assumes a command worked because it
exited successfully. It reads Git again and reports what it actually found.
A typical feature, start to finish
That last exchange is the design in one line. One repository with unsaved work stops the whole
cleanup, because a half-finished teardown cannot be undone by running it again.
Benefits
- Less repetition. One action covers the repositories you choose, instead of one each.
- Fewer late surprises. Wrong tracking branches are visible on the board and fixable in batch,
rather than discovered when a pull request contains someone else's commits.
- Faster updates. Staleness is checked cheaply across every candidate; the expensive fetch happens
only for what you actually selected.
- Safe cleanup. The tool refuses to delete anything when any selected repository holds uncommitted
or unpushed work, so "is it safe to clean up?" stops being a manual check. The one case it asks
about rather than refusing is a branch you never pushed that holds commits your base has not seen —
it shows you the count, per repository, and nothing is ticked for you.
- Reports you can act on. Every repository is named with its own reason. There is never a count
without the list behind it.
- Works where you work. Windows and Linux, desktop VS Code and
vscode-server.
Constraints
These are deliberate limits, not gaps.
| Constraint |
Why |
| Never rebases. Merge only, under every option |
A rebase rewrites history that may already be shared |
| Never force-pushes, hard-resets or force-cleans |
Each of these can destroy work that exists nowhere else |
| Cleanup is all-or-nothing |
A partial teardown cannot be fixed by re-running it |
| A dirty repository is never touched |
Uncommitted work is yours; the tool stops and says so |
| A branch is force-deleted only where you ticked that repository yourself |
A branch you never pushed can hold commits that exist nowhere else. Refusing the whole run would decide for you; so Cleanup shows the count per repository, ticks nothing, and only then — after the typed confirmation — deletes the ones you chose. A branch that has been pushed is never offered: those commits are one git push from safety |
| A default branch is never deleted — locally or on the remote |
Refused before anything runs |
| Nothing is remembered between runs |
Git is the only source of truth, so there is no stale cache to disagree with it |
| Scope is always chosen, never inferred |
The tool may suggest; it never decides what to act on |
| Shared files are copied once, at creation, and never re-synced |
Your worktree's .env is meant to differ |
| Requires VS Code 1.122+ and Node 22.13+ |
The extension host must be Node 22 |
| No telemetry, no network beyond your own Git remotes |
|
Known limitation. On Windows without Developer Mode or administrator rights, symbolic links are
not permitted, so shared files are copied instead of linked. The run tells you once when this
happens — it is not an error, but the copies will not track later edits to the source.
Feature Toggle Cheat Sheet
There is no feature flag. Every command is available as soon as the extension is installed, and
nothing runs on its own — a command only does work when you invoke it.
|
|
| Enable |
Install the extension |
| Disable |
Disable or uninstall it in the Extensions view |
| Background activity |
None. No watchers, no scheduled runs, no ambient reconciliation |
Environment Configuration
Three settings, all under githubWorktreeUtils.
| Setting |
Built-in default |
What it does |
branchPrefixTemplate |
(empty) |
The branch name Create Worktree suggests. {name} becomes the folder's name, so feats/{name} in abc-123 suggests feats/abc-123. You can always type over it |
sharedFilePatterns |
**/.env |
Which files Create Worktree provisions into a new worktree, and which files Cleanup and Remove Repos check for your edits before deleting one |
searchExclusions |
Node, .NET, Python, Java, Go, Rust, PHP and Ruby build directories |
Directory names to skip when looking for repositories and for shared files |
The two list settings are additive: your entries are added to the built-in defaults rather than
replacing them, and an entry prefixed with ! removes one built-in (!dist).
Why the settings UI shows an empty default. VS Code replaces array settings rather than merging
them, so if the real defaults were declared in the manifest, adding one pattern of your own would
silently discard all the others. The defaults live in the extension instead, and your list is added
to them.
Local
No configuration is required. Point a command at a folder of repositories and it works.
Production
Not applicable — this is a developer tool that runs entirely on your machine. It makes no network
calls except the Git operations a command needs against your own remotes.
- Git — the only external program this extension runs
- VS Code — Command Palette, QuickPick, webview, status bar
It depends on no hosted service of any kind, and it shares no packages with other repositories.
src/extension.ts Registers the six commands; the only file that wires adapters
src/core/commands/ One file per command
src/core/pipeline/ The six-step lifecycle every command follows
src/core/policy/ The safety gates: preflight, execution barrier
src/adapters/git/ The only place Git is ever run
src/webview/ The Show Branches board
package.json Command and settings declarations
Documentation
The full contracts live alongside this repository, in hexasync-ideation-hub/doing/github-utils/
(the authors' working copy — the paths are given so a contributor can find them):
| Document |
What it settles |
README.MD |
Master document — the three laws, constraints, and the reference scripts |
prds/prd-git-utils-2026-08-22/prd.md |
Requirements |
architecture/architecture-git-utils-2026-08-22/ARCHITECTURE-SPINE.md |
Architecture decisions |
epics.md |
Epics, stories and acceptance criteria |
For contributors, CLAUDE.md in this repository carries the working rules.
Licence
See LICENSE.
