Git Worktrees

Het probleem: op meerdere branches tegelijk werken¶

Tot nu toe werkten we altijd in één directory. Je kiest een branch, en Git past de bestanden in die directory aan. Dat werkt prima voor één taak, maar zodra je aan meerdere dingen tegelijk wil werken, wringt het.

Wanneer wil je dat eigenlijk?

• Een feature is half af, en plots is een dringende fix op main nodig (een hotfix).
• Een pull request van iemand anders reviewen of uittesten zonder je eigen werk weg te leggen.
• Experimenteren of in de geschiedenis speuren zonder je huidige branch te bevuilen.
• Een (of meerdere!) coding agent een taak geven terwijl jij zelf verder werkt.

Waarom is dat zo lastig? Omdat een repo standaard één working directory heeft. Die directory hoort bij de branch die op dat moment open staat. Wil je naar een andere branch, dan moet die working directory mee... inclusief al je niet-gecommitte werk.

Je werkt bijvoorbeeld al een uur aan feature-search, als een collega om een dringende hotfix vraagt. Even snel naar main switchen? Git steekt daar een stokje voor:

Git weigert omdat je aanpassing aan hello.py verloren zou gaan bij het switchen naar main.

De onhandige tussenoplossingen¶

Er bestaan een paar klassieke trucs om dit probleem te omzeilen. Ze werken, maar geen enkele is echt aangenaam.

Meerdere clones¶

• git clone in een aparte directory per taak: elke directory werkt als een "eigen" repo.
• Nadelen: elke clone heeft een eigen .git (schijfruimte, traag bij grote repos), branches en remotes lopen uit elkaar, en je werkt zo snel in de verkeerde clone.

git stash / git stash pop¶

• Werk opzijzetten (git stash), switchen, later terugzetten (git stash pop).
• Nadelen: pop botst als de andere branch intussen veranderde, de stash-stack wordt een rommel, stashes hangen aan geen enkele branch (makkelijk "verloren"), en je verliest alle context.

Merk op wat er in dit voorbeeld eigenlijk gebeurt: de aanpassing hoorde inhoudelijk bij feature-search, maar staat nu als losse wijziging op main. Je moet zelf goed bijhouden waar welk werk thuishoort.

"WIP"-commits¶

• Een Work-in-Progress tussencommit maken zodat je kan switchen, later rechtzetten met amend/rebase.
• Nadelen: vervuilde geschiedenis, risico dat een WIP-commit per ongeluk gepusht wordt of in een PR terechtkomt, en CI die op een halve feature draait.

Alle oplossingen op een rij:

Worktrees: de betere oplossing¶

flowchart BT
    G["Git database (.git)<br>geschiedenis · branches · remotes"]
    W1["working directory 1<br>hello · branch main"] --> G
    W2["working directory 2<br>hello-hotfix · branch hotfix"] --> G
    W3["working directory 3<br>hello-agent · branch feature-x"] --> G

$ cat .git
gitdir: /Users/maria/dev/hello/.git/worktrees/hello-hotfix

De belangrijkste commando's:

Een basisvoorbeeld:

Je kan nu gewoon werken in ../hello-hotfix: bestanden aanpassen, tests draaien, committen. Het is een volwaardige working directory met een eigen HEAD en staging area. Na een commit:

git worktree list toont duidelijk dat elke worktree zijn eigen branch en laatste commit heeft. Enkele eigenschappen:

• Eén branch per worktree: een branch kan maar in één worktree tegelijk bestaan. Probeer je het toch, dan weigert Git:

  git switch hotfixfatal: 'hotfix' is already used by worktree at '/Users/bob/dev/hello-hotfix'
  

• Gedeelde geschiedenis: de commit 8e1c3a7 staat onmiddellijk in de hele repo - in alle worktrees, zonder pushen of fetchen. Commandos als git log --all of git branch tonen alles van alle worktrees samen.

• Eigen toestand: elke worktree heeft zijn eigen working directory, staging area en HEAD. Een commit in de ene worktree verandert niets aan de bestanden van de andere.

Vanuit de hoofdrepo kan je de hotfix nu mergen, net als elke andere branch:

En opruimen:

fatal: '../hello-hotfix' contains modified or untracked files, use --force to delete it

git worktree add --detach ../hello-review 22b1b17

Beperkingen¶

Worktrees zijn geen wondermiddel. Hou rekening met:

• Virtuele Python omgeving (uv) is lokaal in elke worktree en moet dus in nieuwe worktrees opnieuw worden aangemaakt (bvb uv sync)
• .gitignore bestanden (bvb. .env) zitten niet in Git en dus ook niet in een nieuwe worktree.
• Opkuis: worktrees en hun branches verdwijnen niet automatisch. Gebruik git worktree list om te zien wat er rondslingert en ruim op wanneer een taak klaar is.

Oefeningen¶

Oefening 1: het probleem voelen¶

Werk in je eigen hello repo.

1. Maak een nieuwe branch feature-search en switch ernaar.
2. Maak een aanpassing in hello.py, maar commit ze niet.
3. Probeer naar main te switchen. Wat gebeurt er?
4. Zet je werk opzij met git stash, switch naar main en haal het terug met git stash pop. Op welke branch staat je aanpassing nu?
5. Bespreek: wat zou er gebeuren als je hier per ongeluk commit? En wat als je de stash was vergeten?
6. Ruim op: git restore hello.py.

Oefening 2: een worktree in de praktijk¶

1. Voer git worktree list uit in je hello repo. Hoeveel worktrees zijn er?
2. Maak een hotfix-worktree aan: git worktree add -b hotfix ../hello-hotfix.
3. Open ../hello-hotfix in VS Code en pas hello.py aan. Commit je wijziging.
4. Keer terug naar je hoofdrepo. Vraag jezelf af: zonder te pushen of te pullen, is de commit van de hotfix hier al bekend? Controleer met git log --all --oneline en git worktree list.
5. Merge de hotfix in main.
6. Ruim op: verwijder de worktree en daarna de branch. Controleer met git worktree list en git branch wat er overblijft.
7. Extra: probeer git switch hotfix terwijl de worktree nog bestaat. Wat gebeurt er?

Worktrees en coding agents¶

Tot hier leek een worktree vooral een handigheidje voor wie vaak van branch wisselt. Maar er is één ontwikkeling die worktrees van handig naar noodzakelijk opwaarderen: coding agents.

Waarom één working directory niet werkt voor agents¶

Een coding agent (OpenCode, Claude Code, Codex, ...) werkt in de working directory. Hij leest en bewerkt bestanden, voert commando's uit, draait tests en maakt commits. Dat is precies wat een agent nuttig maakt, maar ook waar het misgaat zodra er twee dingen tegelijk in die directory gebeuren:

• Twee agents, één directory: beide bewerken dezelfde bestanden. Er is geen enkele foutmelding wanneer agent B het werk van agent A overschrijft; de laatste schrijver wint.
• Jij en een agent: terwijl de agent werkt, staat jouw directory op elk moment in beweging. Je eigen half afgewerkte wijzigingen en die van de agent belanden in dezelfde working tree en dus in dezelfde diff.
• Agents en branches: een branch isoleert je commits, maar niet je bestanden. Twee agents op twee verschillende branches kunnen dus nog steeds niet tegelijk in dezelfde working directory werken: elke git switch verandert de bestanden onder de voeten van de andere agent.

De regel is simpel: één working directory per agent. Precies de isolatie die we krijgen met worktrees.

Het resultaat:

• Echte isolatie: agents kunnen elkaar niet overschrijven.
• Jij blijft verder werken: je eigen working directory blijft gewoon op main staan, zonder stash of WIP-commits. Wat de agents doen, raakt jou niet.
• Parallel werk: je kan twee, drie of meer agents tegelijk verschillende taken laten uitvoeren, elk op een eigen branch + worktree.
• Controle op het einde: elke agent levert een eigen branch op. Je kan dan kiezen wat er in main komt, in welke volgorde.

Worktrees in de praktijk van agent-tools¶

Je zal worktrees steeds vaker tegenkomen, ook als je er zelf geen aanmaakt. Sommige agents maken zelf een worktree per sessie. Claude Code doet dat bijvoorbeeld met claude --worktree feature-x: je krijgt een geïsoleerde directory onder .claude/worktrees/ met een eigen branch.

Tools zoals wt (Worktrunk) beheren volledige worktree-workflows: aanmaken, switchen, opruimen en automatische stappen zoals dependencies installeren. Agent-orchestratoren gebruiken hetzelfde patroon: één taak = één werkdirectory = één branch.

Als developer hoef je dus niet elke worktree zelf aan te maken. Waar het op aankomt:

1. Begrijpen dat een worktree een gewone working directory is, met een eigen branch, binnen dezelfde repo.
2. Herkennen wanneer een tool of agent er een gebruikt: een .git-bestand, een pad buiten je gewone repo-directory, of git worktree list.
3. Beoordelen wat er in die branch gebeurt voor je mergt: git log --all, de diff bekijken, tests draaien.
4. Opruimen wanneer de taak klaar is: git worktree remove en daarna de branch verwijderen.

Een agent-instructie die worktrees respecteert¶

Werkt een agent in zijn eigen worktree, dan moet hij daar ook blijven. Dat leg je vast in de projectinstructies (AGENTS.md) of in de prompt:

## Git-regels

- Je werkt in een eigen worktree: werk uitsluitend in de huidige directory.
- Voer geen `git switch`, `git checkout -b` of `git worktree`-commando's uit.
- Commit je wijzigingen op de branch die hier uitgecheckt is; raak `main` niet aan.
- Draai de tests lokaal voor je commit.

En bij het starten geef je de agent een concrete taak, in de worktree waar hij hoort:

$ cd ../hello-feature-logging
$ opencode run "Voeg logging toe aan hello.py en commit je wijziging op deze branch."

Demo: twee opencode-sessies in aparte worktrees¶

We sluiten af met de workflow waar het in deze les echt om draait: twee agents, één project, twee worktrees.

Samenvatting¶

git worktree add -b <branch> <pad>
git worktree add <pad> <bestaande-branch>
git worktree list
git worktree remove <pad>
git worktree prune