Git worktree v Claude Code: vzporedne seje

Praktične informacije o uporabi Ailoota so v dokumentaciji.

Kaj je git worktree v Claude Code#

Vzporedni zagon več agentov v isti mapi je osnovna težava vibe-codanja pri hitrosti leta 2026. Agenti AI pišejo kodo hitreje, kot lahko človek spremlja, kdo spreminja kaj. Brez izolacije datotek se vzporedni zagon dveh sej Claude Code v istem imeniku konča tako, da ena seja prepiše delo druge.

Git worktree to reši na ravni datotečnega sistema. Imate en glavni imenik, v katerem delate. Ukaz claude --worktree feature-auth ustvari mapo .claude/worktrees/feature-auth/ na ločeni veji in tam zažene Claude Code. Datoteke so izolirane. Spremembe v eni seji drugi niso vidne, dokler jih izrecno ne združite.

Uradna dokumentacija Anthropic to opisuje takole:

Namig za samopreverjanje: če ste že kdaj dobili commit, v katerem je bila polovica datotek delo nekoga drugega, potrebujete worktree.

Kako se git worktree razlikuje od običajne veje#

Običajni potek dela v Gitu: ste na veji main in zaženete git checkout feature-x—Git prepiše datoteke delovne kopije. Zagnani npm run dev se pokvari, ker se je spremenil package.json. Nesprejete spremembe shranite z ukazom stash in počakate, da IDE znova indeksira. Preklopite nazaj in vse je spet prepisano, zato morate ponovno uporabiti stash in pop.

Git worktree ponuja drugo možnost: namesto da med vejami preklapljate eno mapo, ustvarite drugo mapo za drugo vejo. Ukaz git worktree add ../project-feature-x feature-x ustvari imenik ../project-feature-x/ z datotekami z veje feature-x. Vaš main ostane v prvotni mapi, razvojni strežnik pa še naprej deluje.

Prej je bilo treba način worktree v Claude Code nastaviti ročno: git worktree add, nato cd, nato claude—in to ponoviti v vsakem terminalu. Zastavica --worktree (tudi -w) vse tri korake izvede z enim ukazom.

Zagon prve vzporedne seje: zastavica --worktree#

Najkrajši primer. Odprite prvi terminal v korenu projekta:

claude --worktree feature-auth

Claude Code naredi tri stvari:

1. Ustvari .claude/worktrees/feature-auth/ s posnetkom origin/HEAD (običajno vaše privzete veje).
2. Ustvari novo vejo worktree-feature-auth.
3. Zažene sejo v tej mapi.

Odprite drugi terminal v isti korenski mapi repozitorija:

claude --worktree bugfix-123

Končano. Dve seji Claude Code, različne datoteke na disku, različni veji Gita. Če v prvi pišete avtentikacijo, v drugi pa popravljate neuspešen test, si fizično ne moreta biti v napoto.

Če ne želite vpisati imena, si ga bo Claude izmislil:

claude --worktree
# → creates something like .claude/worktrees/bright-running-fox/

Namig za začetnike v Gitu: dodajte .claude/worktrees/ v .gitignore. Sicer boste ob zagonu git status v glavni mapi vsebino vseh worktreejev videli kot nesledene datoteke:

# .gitignore
.claude/worktrees/

Napaka, ki se ji je treba izogniti: pred prvim zagonom --worktree v novem imeniku ga odprite z običajnim ukazom claude (brez zastavice) in sprejmite pogovorno okno za zaupanje delovnemu prostoru. Če tega ne storite, zastavica odpove z napako »trust not accepted«—tudi če jo združite z -p za način brez uporabniškega vmesnika.

Kje so worktreeji in kako jih najti#

Privzeta lokacija je določena: .claude/worktrees/<value>/ v korenu repozitorija. Če je vaš projekt v ~/dev/my-app/, bo worktree feature-auth v ~/dev/my-app/.claude/worktrees/feature-auth/.

Za nestandardne postavitve (na primer, če želite worktree zunaj repozitorija) je na voljo hook WorktreeCreate—več o tem v spodnjem razdelku o SVN in Mercurialu.

Znotraj ene seje Claude lahko preklopite na drug obstoječi worktree. V klepet preprosto napišite: »preklopi na .claude/worktrees/bugfix-123« in Claude bo poklical orodje EnterWorktree. Trenutna mapa bo ostala nespremenjena—vrnete se lahko na enak način.

Standardni ukaz Gita prikaže seznam vseh worktreejev, vključno z glavnim in ročno ustvarjenimi:

git worktree list

Izhod bo podoben temu:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

Kopiranje .env in skrivnosti: datoteka .worktreeinclude#

Ko --worktree ustvari novo mapo, vsebuje le datoteke, ki so v Gitu. .env s ključi API in .env.local z lokalno konfiguracijo sta v .gitignore, zato ju v worktreeju ni. Prvi npm run dev se zato konča z napako »MISSING DATABASE_URL«.

Domača rešitev je, da po vsakem --worktree ročno kopirate .env. Enkrat deluje, potem pa na to pozabite. Anthropicova rešitev je datoteka .worktreeinclude v korenu projekta, v kateri so navedene datoteke, prezrte v Gitu, ki se samodejno kopirajo v vsak nov worktree.

V korenu repozitorija ustvarite datoteko .worktreeinclude:

.env
.env.local
config/secrets.json

Sintaksa je enaka kot pri .gitignore. Uporabite lahko vzorce glob:

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic navaja jasno pravilo za preprečevanje nezgod:

Z drugimi besedami, prek .worktreeinclude ne morete po nesreči kopirati datoteke package.json—ni v .gitignore. Vanjo lahko varno dodate poljubne vzorce.

Ista datoteka .worktreeinclude deluje v treh načinih: ročni --worktree, samodejni worktreeji za podagente (glejte spodaj) in seje v namizni aplikaciji Claude.

Worktree iz pull requesta za pregled kode#

Običajen primer pregleda kode: sodelavec je poslal PR; pregledati morate kodo, zagnati teste in pustiti komentar. Z običajnim git checkout pull/1234/head znova preklopite delovno kopijo in prekinete aktivno sejo.

Z zastavico --worktree za to potrebujete en ukaz:

claude --worktree "#1234"

Kaj se zgodi: Claude Code zažene git fetch origin pull/1234/head, ustvari worktree v .claude/worktrees/pr-1234/ in opravi checkout veje PR. Seja se zažene. Takoj ga lahko prosite, naj »prebere diff, zažene teste in poišče logične napake«—medtem ko Claude dela, vaša glavna seja na veji main še naprej deluje.

Druga možnost je celoten URL pull requesta:

claude --worktree https://github.com/OWNER/REPO/pull/1234

V resničnem projektu kombinacija claude --worktree "#N" z vašim podagentom za pregled kode omogoča samodejni pregled v minuti ali dveh. Zaženite ga v ozadju, nadaljujte delo v glavnem oknu in si oglejte rezultat z ukazom claude agents.

Osnovna veja: worktree.baseRef za fresh ali head#

Privzeta nastavitev je naslednja: vsak nov worktree se začne pri origin/HEAD. Prednost je čist začetek, za katerega je zagotovljeno, da ustreza temu, kar bo videl CI. Slabost pa je, da v novem worktreeju ne bodo vključene nesprejete spremembe ali več lokalnih commitov na trenutni veji, ki presegajo stanje oddaljenega repozitorija.

Za začetek delovnega drevesa iz trenutnega lokalnega commita HEAD to dodajte v .claude/settings.json ali globalne nastavitve:

{
  "worktree": {
    "baseRef": "head"
  }
}

Zdaj claude --worktree experimental-feature začne iz trenutnega lokalnega HEAD. Koristi pri funkciji z lokalnimi še nepotisnjenimi commiti. Sledene nepotrjene spremembe niso vključene. Če jih podagent potrebuje, zahtevane spremembe izrecno ohranite in prenesite ter preglejte ciljni diff; prenosa ne zamenjujte z .worktreeinclude, ki obravnava prezrte lokalne datoteke.

Nastavitev sprejema natanko dve vrednosti: "fresh" (= origin/HEAD) in "head" (= lokalni HEAD). Poljubni refi, kot sta "feature-branch" ali hash commita, niso podprti—ta omejitev je namerna, da prepreči kombinatorično eksplozijo možnosti.

Samodejna izolacija podagentov: isolation: worktree#

Ko Claudeu naročite »zaženi tri podagente: eden naj prebere podatkovno zbirko, drugi pregleda API, tretji pa preveri teste«, vsi trije privzeto delajo v vaši delovni kopiji. Če vsaj dva hkrati pišeta v isto datoteko, pride do konflikta. Rešitev je, da vsak samodejno dobi svoj worktree.

1. način: ustno prosite. Claudeu v pogovoru napišite:

Za svoje agente uporabi worktreeje.

Claude bo izolacijo uporabil za vse naslednje podagente v tej seji.

2. način: nastavite jo izrecno v samem podagentu. V datoteko podagenta (na primer .claude/agents/code-reviewer.md) dodajte polje v frontmatter:

---
name: code-reviewer
description: Prebere diff in napiše komentarje za pregled kode
isolation: worktree
---

Natančen pregledovalec si. Preberi diff in poišči logične napake...

Vsak zagon tega podagenta zdaj dobi začasni worktree v .claude/worktrees/. Če podagent ni ničesar zapisal, se mapa samodejno izbriše, ko konča. Če so v njej nesprejete spremembe, vas Claude vpraša, ali jih želite obdržati ali odstraniti.

Osnovna veja za worktreeje podagentov je enaka kot pri --worktree: privzeto origin/HEAD, z worktree.baseRef: head pa lokalni HEAD.

Odločitvena matrika: worktree, /bg, podagent ali Agent View#

Značilne kombinacije:

• »2 funkciji vzporedno, ročno« — dva terminala, vsak izvaja claude --worktree. Najpreprostejši primer.
• »Zaženi nočni refaktor; zaprl bom aplikacijo« — /bg + /goal s pogojem dokončanja. Seja teče neodvisno od vašega okna.
• »En poziv, tri vzporedne raziskave« — trije podagenti z isolation: worktree. Vsak v svojem peskovniku.
• »Kaj se trenutno izvaja?« — claude agents. Nadzorna plošča vseh sej s filtri »running«, »blocked« in »done«.

5 pasti pri delu z worktreeji#

1. Zagnali ste worktree, .env manjka in nič ne deluje. To je najpogostejša težava. Worktree je svež checkout brez datotek, ki jih Git prezre. Rešitev je, da takoj ob nastavitvi načina worktree ustvarite datoteko .worktreeinclude z vzorcem .env* in potrebnimi lokalnimi konfiguracijami. Preverite, ali je datoteka v korenu repozitorija in ne v .claude/.

2. Želite preklopiti na glavno vejo, zaženete cd v koren in izgubite nesprejete spremembe v worktreeju. Korenska mapa in worktree sta različni delovni kopiji. Z ukazom cd ste se vrnili; spremembe v worktreeju so ostale na mestu—niso izginile. Če pa ste se zmedli in v glavni mapi zagnali git stash, ker ste mislili, da ste v worktreeju, bo stash ustvarjen na glavni veji, ne na tisti, na kateri ste ga pričakovali.

3. Zagnali ste 5 vzporednih sej in se ne spomnite več, kaj dela katera. Dokumentacija Anthropic izrecno opozarja, da večina razvijalcev kognitivno ne zmore obvladati več kot 2–3 sej. Znak preobremenitve je, da odprete Agent View in ne morete takoj povedati, kaj počne posamezen agent. Omejite se na dve sočasni seji. Če naloga zahteva več, jo je treba orkestrirati prek /goal + podagentov, ne ročno.

4. Worktreeji iz -p (brez uporabniškega vmesnika) se ne očistijo samodejno. Ukaz claude --worktree feature-x -p "do thing" ne prikaže interaktivnega poziva ob izhodu, zato Claude nikoli ne vpraša »odstranim worktree?« Ti worktreeji se kopičijo. Odstranite jih ročno: git worktree remove .claude/worktrees/feature-x. Ali uporabite cron-skript, ki odstrani vse, kar je starejše od 7 dni.

5. Pogovorno okno za zaupanje v novi mapi. Če repozitorij odprete prvič in takoj zaženete claude --worktree, ukaz ne bo uspel. Zaženite claude brez zastavic, sprejmite zaupanje delovnemu prostoru in zaprite—nato bo --worktree deloval. To je namerno, da Claude ne dobi dostopa do tujega projekta brez uporabnikovega soglasja.

Čiščenje: kaj se samodejno izbriše#

Logika čiščenja je odvisna od tega, kaj ste počeli v worktreeju in kako ste zagnali sejo. Dokumentacija Anthropic navaja tri scenarije:

Scenarij 1: vstopili ste, niste naredili ničesar in izstopili—worktree je bil odstranjen.

Scenarij 2: nekaj ste naredili, vendar tega niste commitali—Claude ob izhodu vpraša »obdržim ali odstranim?« Izbira »obdrži« shrani mapo in vejo za pozneje. »Odstrani« izbriše imenik skupaj z nesprejetimi spremembami in novimi commiti. To je destruktivno—ne kliknite »odstrani« iz navade.

Scenarij 3: zagnali ste -p (brez uporabniškega vmesnika), ukaz pa se je končal in zaprl. Worktree ostane. Očistite ga ročno:

git worktree remove .claude/worktrees/feature-x

Poleg tega se worktreeji podagentov in sej /bg samodejno odstranijo s čiščenjem v ozadju, če so starejši od cleanupPeriodDays dni (nastavitev, ki je običajno privzeto 30 dni) in nimajo neshranjenega dela. Samodejno čiščenje se worktreejev iz --worktree ne dotakne—zanje ste odgovorni vi.

Alternative za SVN, Perforce in Mercurial: hook WorktreeCreate#

Če repozitorij uporablja Subversion ali Mercurial, zastavica --worktree ne bo delovala neposredno. Anthropic ponuja razširitveno točko prek dveh hookov: WorktreeCreate (ustvari izolirano kopijo) in WorktreeRemove (jo odstrani).

Primer SVN-hooka iz uradne dokumentacije:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

Hook prebere ime worktreeja iz stdin ({ "name": "feature-auth" }), zažene svn checkout v vnaprej določeni imenik in pot izpiše na stdout—Claude Code jo uporabi kot delovni imenik za novo sejo.

Pomembno opozorilo: pri uporabi lastnega hooka se .worktreeinclude ne uporablja. Če v novi mapi potrebujete .env ali druge datoteke, ki jih Git prezre, jih kopirajte znotraj skripta hooka.

Kaj sledi: trije sorodni mehanizmi za vzporedno delo#

Worktree zagotavlja izolacijo datotek. /bg zagotavlja izolacijo konteksta. Podagenti zagotavljajo izolacijo nalog. Vsak mehanizem sam zase rešuje en problem. Skupaj omogočajo delo na treh do petih vzporednih nalogah brez kognitivnega zloma. To je nabor spretnosti za napredno vibe-codanje leta 2026.

Ta tema se naravno nadaljuje s tremi sorodnimi temami: kako nastaviti avtonomnega agenta z /goal in Agent View, kako ustvariti lastne podagente za svoje naloge in kako zagnati stotine agentov prek Dynamic Workflows.

Odprite Ailoot.