Claude Code ja git worktree: näin ajat useaa sessiota rinnakkain

Kun Claude Code tekee pitkää tehtävää, tulee helposti kiusaus avata toinen terminaali ja pyytää toista sessiota korjaamaan pieni bugi samalla. Samassa kansiossa se on huono idea. Kaksi sessiota muokkaa samoja tiedostoja, toinen ajaa testejä toisen keskeneräisen koodin päällä, ja lopulta kumpikaan ei tiedä, mikä muutos on kenenkin.

Ratkaisu on git worktree. Jokainen sessio saa oman kopion tiedostoista ja oman haaran, mutta historia ja remote ovat yhteiset. Claude Codessa tähän on valmis lippu, joten mitään skriptejä ei tarvitse rakentaa. Käydään läpi, miten se toimii, mihin se kompastuu ja milloin siitä on oikeasti hyötyä.

Mikä on git worktree?

Tavallisesti yhdellä repositoriolla on yksi työkansio. Vaihdat haaraa komennolla git switch, ja tiedostot kansiossa vaihtuvat. Kaksi haaraa ei voi olla auki samaan aikaan.

Worktree muuttaa tämän. Se on erillinen työkansio, jolla on omat tiedostot ja oma haara, mutta joka käyttää samaa .git-hakemistoa kuin pääkansio. Commitit, haarat ja remote näkyvät molemmista. Tiedostot taas ovat aidosti erilliset: kun muokkaat jotain yhdessä worktreessa, toinen ei huomaa mitään.

Tämä sopii Claude Codelle hyvin. Yksi sessio rakentaa uutta ominaisuutta, toinen korjaa bugia, eikä kumpikaan näe toisen keskeneräisiä tiedostoja.

Jos git on vielä vähän vieras, käy ensin läpi Claude Coden ja gitin perusteet. Worktreet ovat helppo juttu, kun haarat ja commitit ovat tuttuja.

Näin käynnistät Claude Coden worktreessa

Komento on lyhyt. Aja se repositorion sisällä:

claude --worktree feature-auth

Lyhyempi muoto on claude -w feature-auth. Claude Code luo worktreen oletuksena kansioon .claude/worktrees/feature-auth/ repositorion juureen ja tekee sille uuden haaran nimeltä worktree-feature-auth. Sessio käynnistyy suoraan siellä.

Toinen rinnakkainen sessio syntyy samalla tavalla, kunhan avaat toisen terminaalin ja annat eri nimen:

# Terminaali 1
claude -w feature-auth

# Terminaali 2
claude -w fix-login-redirect

Jos jätät nimen pois, Claude Code keksii sellaisen itse, esimerkiksi bright-running-fox. Nimi kannattaa silti antaa, koska kolmen session jälkeen kukaan ei muista, mikä kettu teki mitäkin.

Kolme pientä asiaa ennen kuin lähdet:

• Lisää .claude/worktrees/ tiedostoon .gitignore. Muuten worktreiden sisältö näkyy pääkansiossa seuraamattomina tiedostoina.
• Repositoriossa pitää olla vähintään yksi commit. Worktree luodaan olemassa olevasta commitista. Tyhjässä kansiossa aja ensin git init ja tee ensimmäinen commit.
• Interaktiivinen ajo vaatii, että olet hyväksynyt kansion. Jos et ole ajanut Claude Codea kyseisessä kansiossa ennen, aja kerran pelkkä claude ja hyväksy luottamusdialogi. Muuten --worktree päättyy virheeseen.

Voit myös pyytää worktreetä kesken session. Kirjoita vaikka "tee tämä worktreessa", niin Claude luo sellaisen EnterWorktree-työkalulla ja siirtyy sinne. Kun sessio on eristetty worktreeseen, Claude Code estää sitä muokkaamasta pääkansion tiedostoja omilla muokkaustyökaluillaan ja ajamasta gittiä pääkansiossa. Shell-komento, joka kirjoittaa pääkansioon ajamatta gittiä, kuten cp, ei kuitenkaan esty, joten eristys ei ole aukoton.

Ympäristö kuntoon: .env, riippuvuudet ja .worktreeinclude

Tässä kohtaa moni kompastuu ensimmäisellä kerralla. Worktree on tuore checkout, joten siinä on vain gitin seuraamat tiedostot. .env, .env.local ja muut gitignoroidut tiedostot puuttuvat, eikä node_modules-kansiota ole. Sovellus ei käynnisty, testit kaatuvat ja Claude alkaa ihmetellä puuttuvia ympäristömuuttujia.

Ympäristötiedostojen ratkaisu on .worktreeinclude. Se on projektin juureen tuleva tiedosto, jossa luettelet kopioitavat tiedostot samalla syntaksilla kuin .gitignore-tiedostossa:

.env
.env.local
config/secrets.json

Claude Code kopioi vain tiedostot, jotka täsmäävät johonkin riviin ja ovat lisäksi gitignoroituja. Seurattuja tiedostoja ei siis kopioida tuplana. Sama koskee kaikkia Claude Coden gitillä luomia worktreitä: --worktree-sessioita, subagenttien worktreitä ja työpöytäsovelluksen rinnakkaisia sessioita.

Riippuvuudet ovat oma juttunsa. Älä laita node_modules-kansiota .worktreeinclude-tiedostoon, koska tiedostot kopioidaan eikä linkitetä, eli jokainen worktree saisi täyden kopion. Vaihtoehtoja on kaksi:

1. Asennuskomento CLAUDE.md-tiedostoon. Kirjoita sinne esimerkiksi "Uudessa checkoutissa aja ensin npm ci". Claude ajaa sen aina, kun se aloittaa uudessa worktreessa. Ohjeen kirjoittamisesta lisää oppaassa hyvän CLAUDE.md-tiedoston kirjoittamiseen.
2. worktree.symlinkDirectories-asetus. Se linkittää isot kansiot pääkansiosta jokaiseen worktreeseen:

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"]
  }
}

Symlinkki säästää levytilaa ja aikaa, mutta kaikki työkalut eivät toimi symlinkatun kansion kanssa. Jos build alkaa kaatua, valitse ensimmäinen vaihtoehto ja anna Clauden asentaa riippuvuudet.

Mistä haarasta worktree lähtee

Oletuksena uusi worktree haarautuu repositorion oletushaarasta remotessa, yleensä main-haarasta. Se on useimmiten juuri oikein: sessio aloittaa puhtaalta pöydältä, eikä mukana kulje mitään keskeneräistä.

Joskus haluat kuitenkin, että uusi sessio jatkaa sinun nykyisestä työstäsi, vaikka sitä ei ole vielä pushattu. Silloin worktree.baseRef hoitaa asian:

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

Arvoja on kaksi: "fresh" (oletus, remoten oletushaara) ja "head" (paikallinen HEAD, eli pushaamattomat commitit tulevat mukaan). Haaran nimeä asetus ei hyväksy. Jos haluat worktreen tietystä olemassa olevasta haarasta, tee se gitillä käsin, siitä alempana.

Pull requestin voi avata suoraan omaan worktreeseen. Anna numero risuaidan kanssa ja laita se lainausmerkkeihin, ettei shell tulkitse risuaitaa kommentiksi:

claude --worktree "#1234"

Claude Code hakee PR:n head-commitin origin-remotesta ja luo worktreen kansioon .claude/worktrees/pr-1234. Myös GitHubin PR-osoite ja GitLabin merge requestin osoite käyvät. Tämä on kätevä tapa katselmoida jonkun toisen muutos koskematta omaan työkansioon.

Esimerkki: ominaisuus ja bugikorjaus yhtä aikaa

Kuvitellaan tavallinen Next.js-projekti nimeltä kauppa. Olet aloittanut uuden hakusivun, ja samaan aikaan joku raportoi, että kirjautumisen jälkeinen uudelleenohjaus vie väärälle sivulle.

Ensin kertaluontoinen valmistelu projektin juuressa:

cd ~/projektit/kauppa
echo ".claude/worktrees/" >> .gitignore
printf ".env\n.env.local\n" > .worktreeinclude
git add .gitignore .worktreeinclude
git commit -m "Worktree-asetukset"

Sitten kaksi sessiota kahteen terminaaliin:

# Terminaali 1: isompi työ
claude -w hakusivu

# Terminaali 2: pieni korjaus
claude -w fix-login-redirect

Ensimmäiselle sessiolle annat laajan tehtävän, vaikkapa suunnitelman kautta. Isommissa töissä kannattaa käyttää plan modea, jolloin Claude tutkii koodin ja ehdottaa toteutusta ennen kuin muuttaa mitään. Toiselle sessiolle annat tarkan, rajatun pyynnön:

Kirjautumisen jälkeen käyttäjä ohjataan etusivulle, vaikka hän
tuli /tilaukset-sivulta. Etsi uudelleenohjauksen logiikka, korjaa
se niin että käyttäjä palaa alkuperäiselle sivulle, ja kirjoita
korjaukselle testi. Aja npm test lopuksi.

Korjaussessio valmistuu todennäköisesti ensin. Kun se on commitannut, pushaat haaran ja avaat PR:n tavalliseen tapaan. Lopetat session, ja Claude Code kysyy, pidetäänkö worktree vai poistetaanko se. Hakusivusessio jatkaa koko ajan rauhassa omassa kansiossaan.

Huomaa, ettei sinun tarvinnut pysäyttää isompaa työtä, stashata mitään tai vaihtaa haaraa kesken kaiken. Juuri tämän takia worktreet ovat olemassa.

Worktreet käsin: git worktree add

--worktree hoitaa useimmat tilanteet, mutta joskus haluat tehdä worktreen itse. Tyypilliset syyt ovat tietty olemassa oleva haara tai sijainti repositorion ulkopuolella. Silloin käytä gittiä suoraan:

# Uusi haara uuteen kansioon
git worktree add ../kauppa-hakusivu -b hakusivu

# Olemassa oleva haara
git worktree add ../kauppa-bugfix fix-issue-456

# Claude käyntiin worktreessa
cd ../kauppa-hakusivu
claude

Listaus ja poisto:

git worktree list
git worktree remove ../kauppa-hakusivu

Käsin tehdyissä worktreissä .worktreeinclude ei auta, koska Claude Code ei luonut niitä. Kopioi .env itse tai pyydä Claudea tekemään se.

Siivous: mitä tapahtuu, kun lopetat session

Worktreet kasautuvat helposti, joten on hyvä tietää, mitä Claude Code tekee itse ja mitä jää sinulle.

Kun lopetat interaktiivisen worktree-session, Claude Code tarkistaa, onko worktreessa muutettuja tai seuraamattomia tiedostoja tai uusia committeja:

Jos valitset poiston, kansio ja haara katoavat kaikkine muutoksineen. Lue kysymys siis ennen kuin painat Enteriä. Jos pidät worktreen, Claude Code tulostaa lopuksi komennon, jolla palaat siihen. Se on muotoa claude --worktree hakusivu --resume.

Ei-interaktiiviset ajot komennolla claude -p --worktree ovat poikkeus. Niissä ei ole lopetuskysymystä, joten Claude Code ei siivoa niiden worktreitä. Poista ne itse:

git worktree remove .claude/worktrees/yoajo

Jos git kieltäytyy, koska worktree on lukittu, aja ensin git worktree unlock samalle polulle. Lisää -p-ajoista ja skripteistä kertoo headless-automaation opas.

Palaa worktree-sessioon myöhemmin

Isompi työ jää harvoin yhteen istumaan. Jos pidit worktreen lopettaessasi, pääset takaisin samalla nimellä:

claude --worktree hakusivu --resume

Kun worktree samalla nimellä on jo olemassa, Claude Code avaa sen eikä luo uutta. Yksi yksityiskohta kannattaa tietää. Oletusasetuksilla käy näin: jos worktree on puhdas, se on yhä Claude Coden sille luomalla haaralla, eikä sillä ole omia committeja, se nollataan oletushaaraan eikä jatka vanhasta kohdasta. Sama tapahtuu, jos sen PR on yhdistetty ja etähaara poistettu. Muuten worktree avautuu siitä, mihin jäit.

Nimetty sessio on helpompi löytää kuin kettunimi. Anna nimi heti käynnistyksessä lipulla -n tai kesken session komennolla /rename:

claude -w hakusivu -n hakusivu

Nyt claude --resume hakusivu löytää session myöhemmin. Kun jatkat sessiota, joka päättyi worktreen sisällä, Claude Code palauttaa sen samaan worktreeseen. Jos worktree on poistettu välissä, sessio jatkuu siinä kansiossa, josta käynnistit Clauden, ja Claude Code kertoo, ettei worktreetä enää ole.

Jos käytät tmuxia, lippu --tmux luo worktreelle oman tmux-session. Se toimii vain yhdessä --worktree-lipun kanssa:

claude -w hakusivu --tmux

Kun worktree ei synny

Useimmiten --worktree vain toimii. Kun ei toimi, syy on yleensä jokin näistä:

• Can only use --worktree in a git repository. Kansio ei ole git-repositorio. Aja git init, tee ensimmäinen commit ja yritä uudelleen. Jos et tarvitse eristystä, käynnistä Claude ilman lippua.
• Symlinkki polussa. Claude Code kieltäytyy luomasta worktreetä, jos .claude, .claude/worktrees tai itse worktree-kansio on symlinkki. Virheilmoitus kertoo, mikä polku on kyseessä. Poista symlinkki ja yritä uudelleen.
• LFS-tiedostot näkyvät osoitintiedostoina. Jos asensit LFS:n komennolla git lfs install --local, Claude Coden luomaan worktreeseen tulee osoitintiedostot oikeiden tiedostojen sijaan. Aja worktreessa git lfs pull.
• Kansio kuuluu toiseen repositorioon. Virheet belongs to a different repository ja is a leftover worktree tulevat yleensä, kun projekti on kopioitu tai siirretty. Anna worktreelle eri nimi.

Subagentit omissa worktreissaan

Worktreet eivät ole pelkästään sinun avaamiasi sessioita varten. Myös subagentit voivat tehdä työnsä omissa worktreissaan, jolloin rinnakkaiset muokkaukset eivät törmää.

Kertaluontoisesti riittää pyyntö "käytä agenteille worktreitä". Pysyvästi sen saa omaan subagenttiin lisäämällä frontmatteriin isolation: worktree. Tämä tiedosto kansiossa .claude/agents/ ajaa aina omassa worktreessaan:

---
name: refactorer
description: Tekee mekaanisia refaktorointeja moneen tiedostoon
isolation: worktree
---

Tee pyydetty refaktorointi jokaiseen tiedostoon, jota se koskee,
aja sitten testit ja raportoi tulokset.

Subagentin worktree poistuu itsestään, jos agentti lopettaa tekemättä muutoksia. Jos muutoksia jäi, worktree jää levylle, kunnes Claude Coden ajoittainen siivous voi poistaa sen menettämättä työtä. Siivous noudattaa cleanupPeriodDays-asetusta.

Isoihin mekaanisiin muutoksiin on valmis komento /batch. Annat sille ohjeen, esimerkiksi /batch migrate src/ from JavaScript to TypeScript. Se tutkii koodin, jakaa työn 5:stä 30:een itsenäiseen osaan ja näyttää suunnitelman. Kun hyväksyt sen, jokainen osa saa oman taustasubagentin omassa worktreessaan, ja jokainen avaa PR:n tai raportoi, mitä tapahtui. Muut sisäänrakennetut komennot löytyvät slash-komentojen oppaasta.

Mitä worktreet jakavat pääkansion kanssa

Worktree on erillinen tiedostojen osalta, mutta osa asioista on yhteisiä:

• .git-hakemisto. Commitit, haarat ja remote ovat samat. Commit yhdessä worktreessa näkyy heti muissa.
• Pluginit. Pääkansiosta projektitasolle asennetut pluginit latautuvat myös saman repositorion worktreissä.
• Lupahyväksynnät. Kun valitset worktree-sessiossa Bash-komennolle "Yes, and don't ask again", sääntö tallentuu pääkansion tiedostoon .claude/settings.local.json ja pätee kaikissa worktreissä. Poikkeuksena on esimerkiksi Windows, jossa sääntö jää siihen worktreeseen. Lupien logiikka on selitetty tarkemmin oikeuksien ja asetusten oppaassa.
• Auto memory. Clauden itse kirjoittamat muistiinpanot ovat repositoriokohtaisia, joten kaikki saman repositorion worktreet jakavat ne.

Yksi asia ei kulje mukana: gitignoroitu CLAUDE.local.md on olemassa vain siinä worktreessa, jossa loit sen. Jos haluat henkilökohtaiset ohjeet kaikkiin worktreihin, tuo ne CLAUDE.md-tiedostoon kotihakemistosta @-importilla. Muistin ja CLAUDE.md-tiedostojen latautumisesta kerrotaan tarkemmin kontekstia ja muistia käsittelevässä oppaassa.

Milloin rinnakkaisuus kannattaa ja milloin ei

Worktreet tekevät rinnakkaisista sessioista turvallisia, mutta eivät automaattisesti järkeviä.

Kannattaa, kun tehtävät ovat oikeasti erillisiä. Ominaisuus ja bugikorjaus eri puolilla koodia. Dokumentaation päivitys samalla kun toinen sessio kirjoittaa testejä. PR:n katselmointi omassa worktreessaan ilman, että oma työ häiriintyy.

Ei kannata, kun sessiot muokkaavat samoja tiedostoja. Worktree estää törmäyksen vain tekovaiheessa. Kun yhdistät haarat, git kohtaa samat ristiriidat kuin muulloinkin. Kaksi sessiota, jotka refaktoroivat saman moduulin kahteen suuntaan, tuottavat sinulle merge-ristiriidan eivätkä mitään muuta.

Sinä olet pullonkaula. Jokainen sessio tarvitsee ohjeet, välillä tarkennusta ja lopuksi katselmoinnin. Kahta tai kolmea sessiota on vielä helppo seurata. Kymmenen kanssa katselmoit lähinnä sokkona.

Käyttö kasvaa. Jokainen sessio lähettää omat pyyntönsä mallille, joten kolme sessiota kuluttaa käyttörajaa nopeammin kuin yksi. Omaa käyttöäsi voi seurata komennolla /usage, ja hinnoittelun perusteet löytyvät Claude Coden hintaoppaasta.

Toinen sessio katselmoijana

Yksi hyödyllisimmistä tavoista käyttää rinnakkaista sessiota ei liity vauhtiin lainkaan. Toinen sessio on helpoin riippumaton katselmoija, jonka saat.

Idea on yksinkertainen. Ensimmäinen sessio kirjoittaa vaikkapa rate limiterin. Toinen sessio, joka ei ole nähnyt kirjoittamista, saa katselmoitavakseen valmiin tiedoston:

Katselmoi @src/middleware/rateLimiter.ts. Etsi bugeja, reunatapauksia
ja kohtia, joissa raja voi vuotaa. Älä muokkaa mitään, listaa vain
löydökset vakavuuden mukaan.

Kopioit löydökset takaisin ensimmäiseen sessioon ja pyydät korjaukset. Katselmoija ei ole sitoutunut omiin aiempiin ratkaisuihinsa, koska se ei tehnyt niitä. Siksi se huomaa asioita, jotka kirjoittaja ohittaa.

Yhteenveto

Worktreet ovat Claude Coden yksinkertaisin tapa tehdä kahta asiaa kerralla ilman sotkua. Komento on claude -w nimi, .worktreeinclude tuo .env-tiedostot mukaan, ja riippuvuudet asennetaan uudessa kansiossa. Puhtaat sessiot siivoutuvat itsestään, ja -p-ajojen jäljet poistat itse.

Aloita kahdella sessiolla ja kahdella selvästi erillisellä tehtävällä. Kun se tuntuu luontevalta, kokeile katselmoijasessiota tai /batch-komentoa isoon mekaaniseen muutokseen. Lisää käytännön niksejä löytyy Claude Coden käytännön vinkeistä.

Muut Claude Code -artikkelit aiheittain löydät Claude Code -oppaiden sivulta.