chinthakat Parallel worktrees
Git worktrees give each session its own working directory and its own branch. What they do not give each session is its own object store, stash stack, branch namespace, or anything outside git at all. Almost every surprise comes from assuming isolation that is not there.
1. Know which checkout you are in, before you touch anything
Not the branch — the directory. The same branch can be checked out in several places, and the instructions for "run the deploy from here" usually mean one specific path.
git rev-parse --show-toplevel # which worktree am I in
git worktree list # what else exists, and on what branch
git status -sb # branch, ahead/behind, dirty
Do this at the start of a session and again after anything that changes directory. Paths in project docs are frequently relative to one particular checkout.
2. What is shared, and what is not
| Shared across every worktree | Private to each worktree |
|---|---|
| Objects, refs, remotes | Working tree |
| The stash stack | Index |
| Branch names (a branch is checked out in one place at most) | HEAD |
| Hooks, most config | Untracked and ignored files |
| Everything outside git: databases, ports, cloud resources, locks | Local env files, build output |
The stash stack is the one that catches people, because nothing about
git stash suggests it is global.
3. Never use bare git stash or git stash pop
With concurrent sessions, stash@{0} is whatever was pushed most recently by
anyone. A bare pop can silently take someone else's work and drop it into
your tree, corrupting both sessions in a way that is hard to notice and harder
to undo.
The safe alternative, in order of preference:
- A temporary commit.
git commit -am "wip"on your own branch, thengit reset --soft HEAD~1later. It is per-worktree, it is recoverable from the reflog, and it cannot be taken by anyone else. - A tagged stash, applied by hash:
git stash push -u -m "my-unique-tag"
git stash list --format='%H %gs' # capture YOUR entry's hash
git stash apply <hash> # apply, never pop
git stash drop <the stash@{n} that matches your tag now>
Re-find the index by tag before dropping. Positions shift as other sessions push and drop.
4. Shared resources outside git need a protocol
Databases, local servers, fixed ports, cloud stacks, deploy pipelines and test accounts are shared by every session on the machine.
- Per-worktree ports. Derive the port from the directory name or keep a small map, and start the dev server through a wrapper that applies it. Two sessions racing for port 5173 produce an extremely confusing afternoon in which one session's changes appear in the other's browser.
- One designated worktree for deploys and production-data scripts. Not because the code differs, but because the humans need one place to look.
- A real lock for anything that must not run twice — a conditional write to a small table, a CI concurrency group — with a status command and a TTL.
- Shared local services started once, from a documented checkout, not by whichever session got there first.
5. Branches are a shared namespace
A branch can be checked out in exactly one worktree. git checkout other-branch
fails when a sibling holds it, and that error is correct — do not work around it
by force. Create your own branch from the integration branch instead.
Before creating one, check whether the name is taken:
git worktree list && git branch -a --contains HEAD
Never delete a branch you did not create, and never force-push a shared one. If you rebase a branch another worktree has checked out, that worktree's next operation will be baffling.
6. Merge back often
Long-lived parallel branches are where the real cost shows up. Integrate in both directions on a regular cadence — daily is not too often when several sessions are moving:
git fetch origin
git merge origin/develop # take everyone else's work
# ... resolve, test ...
git push # publish yours
Use the repo's sync script if it has one; it usually encodes ordering the raw commands do not.
7. Changes you did not make are not necessarily wrong
When a file looks different from what you expect: check git log -5 <file>
before assuming breakage. Another session may have fixed it three minutes ago.
Likewise, do not "tidy" files outside the scope of your task. In a single-session repo that is a small courtesy; here it produces conflicts in someone else's active work.
8. Untracked config does not propagate
Local env files, credentials and scratch directories are per-worktree and usually gitignored, so a new worktree starts without them and fails in ways that look like code problems.
Whatever creates worktrees should copy them, and the README should list what a fresh worktree needs. When something works in one checkout and not another, this is the first thing to check.
Checklist
- Working directory and branch confirmed at the start of the session
- No bare
git stash/git stash pop; WIP commit or tagged stash applied by hash - Ports, local services and cloud resources deconflicted per worktree
- Deploys and data scripts run from the designated checkout, behind a lock
- Own branch created from the integration branch; no force-push on shared branches
- Merged from the integration branch recently
- Unexpected changes checked with
git logbefore being treated as breakage - Untracked local config present in this worktree