Git worktree Claude Code: lygiagrečios sesijos

Praktinės informacijos apie darbą su Ailoot rasite dokumentacijoje.

Kas yra git worktree Claude Code#

Kelių agentų lygiagretus paleidimas tame pačiame aplanke yra pagrindinė vibe-codingo problema 2026 m. tempu. DI agentai rašo kodą greičiau, nei žmogus spėja sekti, kas ką keičia. Be failų izoliavimo, paleidus dvi lygiagrečias Claude Code sesijas tame pačiame kataloge viena sesija galiausiai perrašo kitos darbą.

Git worktree šią problemą išsprendžia failų sistemos lygmeniu. Turite vieną pagrindinį katalogą, kuriame dirbate. Komanda claude --worktree feature-auth sukuria aplanką .claude/worktrees/feature-auth/ atskiroje šakoje ir paleidžia Claude Code jame. Failai izoliuoti. Vienos sesijos pakeitimai kitai nematomi, kol jų aiškiai nesujungiate.

Oficialioje Anthropic dokumentacijoje tai apibūdinama taip:

Savikontrolės užuomina: jei kada nors gavote commit, kuriame pusė failų buvo kito žmogaus darbas, jums reikia worktree.

Kuo git worktree skiriasi nuo įprastos šakos#

Įprasta Git eiga: esate main šakoje ir vykdote git checkout feature-x—Git perrašo darbinės kopijos failus. Veikiantis npm run dev procesas sutrinka, nes pasikeitė jo naudojamas package.json. Atidedate nepatvirtintus pakeitimus ir laukiate, kol IDE iš naujo indeksuos failus. Grįžtate atgal ir viskas vėl perrašoma, todėl vėl reikia atlikti stash ir pop.

Git worktree suteikia kitą galimybę: vietoj to, kad tarp šakų perjunginėtumėte vieną aplanką, sukuriate antrą aplanką kitai šakai. Komanda git worktree add ../project-feature-x feature-x sukuria katalogą ../project-feature-x/ su feature-x šakos failais. Jūsų main lieka pradiniame aplanke, o kūrimo serveris veikia toliau.

Anksčiau worktree režimą Claude Code reikėdavo nustatyti rankiniu būdu: git worktree add, tada cd, tada claude—ir kartoti kiekviename terminale. Žyma --worktree (taip pat -w) visus tris veiksmus atlieka viena komanda.

Pirmos lygiagrečios sesijos paleidimas: žyma --worktree#

Minimalus pavyzdys. Atidarykite pirmą terminalą projekto šakniniame kataloge:

claude --worktree feature-auth

Claude Code atlieka tris veiksmus:

1. Sukuria .claude/worktrees/feature-auth/ katalogą su origin/HEAD momentine kopija (paprastai tai numatytoji šaka).
2. Sukuria naują worktree-feature-auth šaką.
3. Paleidžia sesiją šiame aplanke.

Atidarykite antrą terminalą tame pačiame saugyklos šakniniame aplanke:

claude --worktree bugfix-123

Atlikta. Dvi Claude Code sesijos, skirtingi failai diske, skirtingos Git šakos. Jei pirmoje rašote autentifikavimo kodą, o antroje taisote nepavykusį testą, jos fiziškai negali trukdyti viena kitai.

Jei nenorite įvesti pavadinimo, Claude jį sugalvos:

claude --worktree
# → sukuria kažką panašaus į .claude/worktrees/bright-running-fox/

Patarimas Git pradedantiesiems: pridėkite .claude/worktrees/ prie .gitignore. Kitaip pagrindiniame aplanke vykdydami git status matysite visų worktree turinį kaip nesekamus failus:

# .gitignore
.claude/worktrees/

Vengtina klaida: prieš pirmą kartą naujame kataloge paleisdami --worktree, įeikite į jį įprasta claude komanda (be žymos) ir patvirtinkite darbo srities patikimumo dialogą. Jei to nepadarysite, žyma nepavyks ir pateiks klaidą „trust not accepted“—taip pat ir naudojant ją su -p begalviam režimui.

Kur yra worktree ir kaip juos rasti#

Numatytoji vieta nekinta: .claude/worktrees/<value>/ saugyklos šakniniame kataloge. Jei jūsų projektas yra ~/dev/my-app/, feature-auth worktree bus ~/dev/my-app/.claude/worktrees/feature-auth/.

Nestandartiniams išdėstymams (pavyzdžiui, jei norite worktree laikyti už saugyklos ribų) skirtas WorktreeCreate kabliukas—apie jį daugiau sužinosite toliau, dalyje apie SVN ir Mercurial.

Vienoje Claude sesijoje galite pereiti į kitą esamą worktree. Tiesiog pokalbyje pasakykite: „switch to .claude/worktrees/bugfix-123“, ir Claude iškvies EnterWorktree įrankį. Dabartinis aplankas liks nepakeistas—į jį galėsite sugrįžti tokiu pačiu būdu.

Standartinė Git komanda parodo visų worktree sąrašą, įskaitant pagrindinį ir rankiniu būdu sukurtus:

git worktree list

Išvestis atrodys taip:

/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]

.env ir slaptųjų duomenų kopijavimas: failas .worktreeinclude#

Kai --worktree sukuria naują aplanką, jame būna tik tai, kas užkomitinta Git. .env failas su API raktais ir .env.local su vietine konfigūracija įtraukti į .gitignore, todėl worktree jų nėra. Todėl pirmasis npm run dev nepavyksta ir pateikia „MISSING DATABASE_URL“.

Naminis sprendimas—po kiekvieno --worktree rankiniu būdu nukopijuoti .env. Vieną kartą tai suveikia, o vėliau pamirštama. Anthropic sprendimas—projekto šakniniame kataloge esantis .worktreeinclude failas, kuriame išvardyti Git ignoruojami failai, automatiškai kopijuotini į kiekvieną naują worktree.

Sukurkite .worktreeinclude failą saugyklos šakniniame kataloge:

.env
.env.local
config/secrets.json

Sintaksė tokia pati kaip .gitignore. Galite naudoti glob šablonus:

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

Anthropic pateikia aiškią taisyklę, padedančią išvengti nesklandumų:

Kitaip tariant, per .worktreeinclude netyčia nenukopijuosite package.json—jis nenurodytas .gitignore. Ten saugu įrašyti bet kokius šablonus.

Tas pats .worktreeinclude veikia trimis režimais: rankiniu būdu naudojant --worktree, automatiškai kuriant subagentų worktree (žr. toliau) ir dirbant Claude darbalaukio programėlės sesijose.

Worktree iš pull request kodo peržiūrai#

Įprastas kodo peržiūros scenarijus: kolega atsiuntė PR; turite patikrinti kodą, paleisti testus ir palikti komentarą. Naudodami įprastą git checkout pull/1234/head, vėl perjungtumėte darbinę kopiją ir sutrikdytumėte aktyvią sesiją.

Su --worktree žyma tai atliekama viena komanda:

claude --worktree "#1234"

Kas nutinka: Claude Code paleidžia git fetch origin pull/1234/head, sukuria worktree kataloge .claude/worktrees/pr-1234/ ir išsirenka PR šaką. Sesija prasideda. Galite iš karto paprašyti „perskaityti diff, paleisti testus ir rasti logikos klaidas“—kol Claude dirba, jūsų pagrindinė sesija main šakoje tęsiasi.

Alternatyvi sintaksė—visas pull request URL:

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

Naudojimas tikrame projekte: sujungę claude --worktree "#N" su savo kodo peržiūros subagentu, automatinę peržiūrą gausite per minutę ar dvi. Paleiskite jį fone, tęskite darbą pagrindiniame lange, o prie rezultato grįžkite per claude agents.

Pagrindinė šaka: worktree.baseRef reikšmė fresh arba head#

Numatytasis nustatymas toks: kiekvienas naujas worktree pradedamas nuo origin/HEAD. Privalumas—švari pradžia, kuri tikrai atitinka tai, ką matys CI. Trūkumas—jei dabartinėje šakoje turite nepatvirtintų pakeitimų arba kelis vietinius commit, kurių nėra nuotolinėje saugykloje, naujame worktree jų nebus.

Norėdami worktree pradėti nuo dabartinio vietinio HEAD įrašo, šį nustatymą pridėkite prie .claude/settings.json arba bendrųjų nustatymų:

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

Dabar claude --worktree experimental-feature pradeda nuo dabartinio vietinio HEAD. Tai naudinga, kai funkcija jau turi vietinių neišsiųstų įrašų. Dar neįrašyti sekami pakeitimai neįtraukiami. Jei subagentui jų reikia, aiškiai išsaugokite ir perkelkite reikalingus pakeitimus, tada patikrinkite paskirties pakeitimų skirtumus; šio perkėlimo nepainiokite su .worktreeinclude, kuris apdoroja ignoruojamus vietinius failus.

Nustatymas priima tiksliai dvi reikšmes: "fresh" (= origin/HEAD) ir "head" (= vietinis HEAD). Savavališkos nuorodos, tokios kaip "feature-branch", ar commit maiša nepalaikomos—tai sąmoningas apribojimas, neleidžiantis pasirinkčių deriniams pernelyg išaugti.

Automatiškai izoliuokite subagentus: isolation: worktree#

Kai Claude pasakote „paleisk tris subagentus: vienas nagrinėja duomenų bazę, antras apžiūri API, o trečias tikrina testus“, pagal numatytuosius nustatymus visi trys dirba jūsų darbinėje kopijoje. Jei bent du iš jų vienu metu rašo į tą patį failą, kyla konfliktas. Sprendimas—automatiškai kiekvienam skirti atskirą worktree.

1 būdas: paprašykite žodžiu. Parašykite Claude pokalbyje:

Naudok worktree savo agentams.

Claude šioje sesijoje taikys izoliavimą visiems tolesniems subagentams.

2 būdas: aiškiai nustatykite tai pačiame subagente. Subagento faile (pavyzdžiui, .claude/agents/code-reviewer.md) į frontmatter įtraukite lauką:

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

Esi kruopštus peržiūrėtojas. Perskaityk diff ir ieškok logikos klaidų...

Nuo šiol kiekvieną kartą paleidus šį subagentą jam sukuriamas laikinas worktree kataloge .claude/worktrees/. Jei subagentas nieko neįrašė, baigus darbą aplankas automatiškai ištrinamas. Jei yra nepatvirtintų pakeitimų, Claude paklaus, ar juos palikti, ar pašalinti.

Subagentų worktree pagrindinė šaka tokia pati kaip ir --worktree: pagal numatytuosius nustatymus origin/HEAD, o nustačius worktree.baseRef: head—vietinis HEAD.

Sprendimų lentelė: worktree, /bg, subagentas ar Agent View#

Tipiniai deriniai:

• „2 funkcijos lygiagrečiai, rankiniu būdu“ — du terminalai, kiekviename vykdoma claude --worktree. Paprasčiausias atvejis.
• „Paleisk naktinį pertvarkymą; uždarysiu programą“ — /bg + /goal su užbaigimo sąlyga. Sesija vykdoma nepriklausomai nuo jūsų lango.
• „Vienas promptas, trys lygiagretūs tyrimai“ — trys subagentai su isolation: worktree. Kiekvienas savo izoliacinėje aplinkoje.
• „Kas dabar vyksta?“ — claude agents. Visų sesijų skydelis su filtrais „running“, „blocked“ ir „done“.

5 darbo su worktree klaidos#

1. Paleidote worktree, trūksta .env, niekas neveikia. Dažniausia problema. Worktree yra naujai sukurta darbinė kopija be Git ignoruojamų failų. Vos nustatę worktree režimą, įtraukite į .worktreeinclude šabloną .env* ir būtinas vietines konfigūracijas. Patikrinkite, ar failas yra saugyklos šakniniame kataloge, o ne .claude/.

2. Norite pereiti į main šaką, vykdote cd į šakninį katalogą ir prarandate worktree nepatvirtintus pakeitimus. Šakninis aplankas ir worktree yra dvi skirtingos darbinės kopijos. Grįžote su cd; worktree pakeitimai liko savo vietoje—niekur nedingo. Tačiau jei susipainiojote ir pagrindiniame aplanke paleidote git stash, manydami, kad esate worktree, stash bus sukurtas pagrindinėje šakoje, o ne toje, kurioje tikėjotės.

3. Paleidote 5 lygiagrečias sesijas ir nebeprisimenate, ką kiekviena daro. Anthropic dokumentacijoje aiškiai įspėjama, kad dauguma programuotojų negali mintyse valdyti daugiau nei 2–3 sesijų. Perkrovos požymis—atsidarę Agent View negalite iš karto pasakyti, ką daro kiekvienas agentas. Apsiribokite dviem vienu metu veikiančiomis sesijomis. Jei užduočiai reikia daugiau, ją reikėtų koordinuoti per /goal + subagentus, o ne rankiniu būdu.

4. -p (begalviu režimu) paleisti worktree automatiškai neišvalomi. Komanda claude --worktree feature-x -p "do thing" nerodo interaktyvaus išėjimo raginimo, todėl Claude neturi progos paklausti „pašalinti worktree?“. Tokie worktree kaupiasi. Išvalykite juos rankiniu būdu: git worktree remove .claude/worktrees/feature-x. Arba naudokite cron scenarijų, kuris pašalina viską, kas seniau nei 7 dienos.

5. Patikimumo dialogas naujame aplanke. Jei saugyklą atidarote pirmą kartą ir iškart vykdote claude --worktree, komanda nepavyks. Vykdykite claude be žymų, patvirtinkite darbo srities patikimumą ir išeikite—tada --worktree veiks. Taip sąmoningai užtikrinama, kad Claude negautų prieigos prie kito žmogaus projekto be naudotojo sutikimo.

Išvalymas: kas ištrinama automatiškai#

Išvalymo logika priklauso nuo to, ką nuveikėte worktree ir kaip paleidote sesiją. Anthropic dokumentacijoje išvardijami trys scenarijai:

1 scenarijus: įėjote, nieko nedarėte ir išėjote—worktree buvo pašalintas.

2 scenarijus: šį tą nuveikėte, bet necommitinote—išeinant Claude paklaus „palikti ar pašalinti?“. Pasirinkus „palikti“, aplankas ir šaka išsaugomi vėlesniam laikui. Pasirinkus „pašalinti“, katalogas ištrinamas kartu su nepatvirtintais pakeitimais ir naujais commit. Tai destruktyvu—nespauskite „pašalinti“ iš įpročio.

3 scenarijus: paleidote su -p (begalviu režimu), komanda baigė darbą ir išėjo. Worktree lieka. Išvalykite jį rankiniu būdu:

git worktree remove .claude/worktrees/feature-x

Be to, subagentų ir /bg sesijų worktree automatiškai pašalinami fono valymo metu, jei jie senesni nei cleanupPeriodDays dienų (tai nustatymas, paprastai pagal numatytuosius parametrus lygus 30 dienų) ir juose nėra neišsaugoto darbo. --worktree sukurti worktree automatinis valymas neliečia—už juos atsakote jūs.

Alternatyvos SVN, Perforce ir Mercurial: WorktreeCreate kabliukas#

Jei saugykla naudoja Subversion arba Mercurial, --worktree žyma neveiks tiesiogiai. Anthropic siūlo išplėtimo galimybę per du kabliukus: WorktreeCreate (sukuria izoliuotą kopiją) ir WorktreeRemove (ją pašalina).

SVN kabliuko pavyzdys iš oficialios dokumentacijos:

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

Kabliukas iš stdin nuskaito worktree pavadinimą ({ "name": "feature-auth" }), vykdo svn checkout iš anksto apskaičiuotame kataloge ir išveda kelią į stdout—Claude Code naudoja jį kaip naujos sesijos darbinį katalogą.

Svarbi pastaba: naudojant savo kabliuką, .worktreeinclude neveikia. Jei naujame aplanke reikia .env ar kitų Git ignoruojamų failų, nukopijuokite juos pačiame kabliuko scenarijuje.

Kas toliau: trys susiję lygiagretaus darbo mechanizmai#

Worktree suteikia failų izoliavimą. /bg suteikia konteksto izoliavimą. Subagentai suteikia užduočių izoliavimą. Kiekvienas mechanizmas atskirai išsprendžia vieną problemą. Kartu jie leidžia dirbti su trimis–penkiomis užduotimis lygiagrečiai ir nepervargti. Tai įgūdžių rinkinys, kuriuo paremtas pažangus vibe-codingas 2026 m.

Ši tema natūraliai siejasi su trimis kitomis: kaip nustatyti autonominį agentą naudojant /goal ir Agent View, kaip sukurti savo užduotims skirtus subagentus ir kaip paleisti šimtus agentų per Dynamic Workflows.

Atidarykite Ailoot.