Slovník pojmů

Git Worktrees

Git Worktrees umožňují mít vedle sebe více pracovních adresářů jednoho repozitáře. Rozpracovaná feature tak může zůstat beze změny, zatímco v druhém adresáři vznikne rychlý hotfix na jiné větvi.

Stručná definice

Více checkoutů nad jedním společným repozitářem.

Git používá příkaz a koncept git worktree pro správu více pracovních stromů připojených k jednomu repozitáři. Hlavní pracovní strom vzniká běžně při git clone nebo git init; další adresáře přidané příkazem git worktree add se označují jako linked worktrees. Přívlastek main u pracovního stromu neznamená, že v něm musí být checkoutnutá větev main.

Worktree není nová větev ani nový klon. Je to konkrétní pracovní adresář s checkoutnutými soubory a vlastními údaji, například HEAD a indexem. Všechny worktrees přitom používají společnou historii, většinu refs a stejnou Git object database, v níž jsou uložené commity, stromy a další objekty.

Jaký problém řeší

Přepnutí kontextu bez stashování rozpracované práce.

Jeden pracovní strom může mít checkoutnutý jediný stav. Přepnutí na jinou větev je nepohodlné, pokud obsahuje necommitnuté změny nebo rozběhnutý vývojový server. Linked worktree poskytne druhý adresář a oddělený index bez nového klonu celé historie.

rychlá oprava z hlavní větve vedle rozpracované feature
současné spuštění dvou verzí aplikace pro porovnání chování
review cizí větve bez přepnutí a úklidu aktuální pracovní kopie
samostatný adresář pro release nebo reprodukci chyby
paralelní práce nad různými větvemi se sdílenou historií

Praktický příklad

Hotfix platebního webhooku vedle rozpracovaného checkoutu.

Vývojář pracuje v hlavním pracovním stromu na feature/new-checkout a nechce rozpracované soubory commitovat ani ukládat do stashe. Z aktuálního commitu větve main proto vytvoří novou větev hotfix/payment-webhook a zároveň ji checkoutne do sousedního adresáře ../shop-hotfix.

V novém adresáři opraví webhook, spustí testy, vytvoří commit a větev odešle k review. Příkaz git worktree list ukáže cestu, commit a branch každého pracovního stromu. Po dokončení se nejprve ověří čistý stav a linked worktree se odstraní řízeným příkazem; hotfix větev a její commity tím z repozitáře nezmizí.

Shell

git worktree add -b hotfix/payment-webhook ../shop-hotfix main
git -C ../shop-hotfix status

# V adresáři ../shop-hotfix uprav, otestuj, commitni a odešli opravu.
git worktree list
git -C ../shop-hotfix status --short

Jak funguje

Jedno úložiště repozitáře → main worktree (feature) + linked worktree (hotfix).

Diagram ukazuje sdílené Git úložiště a oddělené pracovní adresáře. Worktrees sdílejí object database a běžné branch refs, ale každý má vlastní checkout, HEAD, index a rozpracované soubory.

Společný repozitář Object database uchovává společné commity, stromy a blobs. Nový commit vytvořený v jednom worktree je proto známý ostatním.
Main worktree Původní pracovní strom má vlastní HEAD, index a soubory. V příkladu zůstává na feature/new-checkout s rozpracovanou změnou.
Linked hotfix worktree Druhý adresář má vlastní HEAD, index a checkout větve hotfix/payment-webhook.
Nezávislá práce se soubory Změna nebo staging v hotfix adresáři nepřepíše rozpracované soubory ani index feature adresáře.
Řízený úklid Příkaz git worktree remove zkontroluje stav a odstraní linked worktree i jeho administrativní vazbu. Prune je určený pro osiřelá metadata po chybějícím adresáři, ne jako běžná náhrada remove.

Hlavní části a koncepty

Pracovní adresáře jsou oddělené, historie zůstává společná.

Praktické použití stojí na rozlišení repozitáře, pracovního stromu a větve. Každá z těchto vrstev má jiný životní cyklus.

Main a linked worktree

Repozitář, který není bare, má jeden main worktree a může mít další linked worktrees. Linked worktree obsahuje malý soubor .git odkazující na administrativní data ve společném Git adresáři; nemá druhou kompletní databázi .git.

Vlastní HEAD a index

Každý pracovní strom sleduje vlastní checkout a vlastní staging area. Proto lze v jednom adresáři připravovat feature a v jiném hotfix, aniž by se jejich necommitnuté soubory nebo staged změny smíchaly.

Sdílené objekty a refs

Commity, trees a blobs se ukládají do společné object database. Běžné lokální větve jsou také sdílené reference, takže posun větve v jednom pracovním stromu vidí celý repozitář. Některé pseudo-refs, zejména HEAD, jsou naopak specifické pro worktree.

Přidání a výpis

Příkaz git worktree add <cesta> <větev> checkoutne existující větev; varianta s -b <nová-větev> ji vytvoří z určeného commitu. Git worktree list vypíše pracovní stromy a jejich revize.

Move, remove, prune a repair

Pro běžný přesun slouží git worktree move. Remove je standardní úklid dokončeného linked worktree a bez vynucení odmítne nečistý adresář. Prune odstraní osiřelá administrativní data po již chybějících adresářích; předem lze použít git worktree prune --dry-run. Repair opraví zastaralé administrativní vazby po externím přesunu main nebo linked worktree.

Jedna branch, jeden checkout

Git standardně odmítne přidat worktree s lokální větví checkoutnutou jinde. Ochrana brání dvěma adresářům nekontrolovaně posouvat stejnou branch; obcházení pomocí force není běžný postup.

Výhody, omezení a časté chyby

Rychlé paralelní prostředí je současně svázané jedním repozitářem.

Konkrétní přínosy

rozpracovaný adresář zůstane beze změny při opravě jiné větve
společné objekty obvykle šetří disk a další fetch historie proti samostatnému klonu
každý worktree má vlastní index, necommitnuté změny a checkout
jednotný přehled cest a větví přes git worktree list

Omezení a chyby

worktree není záloha, protože závisí na společné historii a administrativních datech repozitáře
ruční smazání adresáře může zanechat metadata; správný postup je git worktree remove
stejnou lokální branch nelze standardně checkoutnout současně ve více worktrees
sdílená repository konfigurace či hooks mohou ovlivnit všechny worktrees
submoduly a některé IDE, dev servery nebo skripty mohou mít při více checkoutech vlastní omezení

Praktické použití a porovnání

Worktree, branch, clone a repository nejsou zaměnitelné pojmy.

Branch je pojmenovaná reference na commit. Worktree je adresář, ve kterém je větev nebo konkrétní commit checkoutnutý. Založení linked worktree může současně vytvořit novou branch, ale tyto dva objekty mají rozdílný účel a lze je spravovat odděleně.

Repozitář zahrnuje historii a Git metadata; pracovní strom je místo, kde se jeho obsah upravuje. Linked worktree proto není druhý Git repository. Sdílí object database, refs a standardně i repository config, zatímco vlastní má HEAD, index a pracovní soubory.

Samostatný git clone má typicky vlastní Git adresář, objektovou databázi, konfiguraci a stav vzdálených refs. Poskytuje silnější provozní oddělení a lze jej nezávisle přesunout nebo smazat, ale spotřebuje další prostor a potřebuje vlastní fetch. Worktrees jsou úspornější a pohodlnější pro větve jednoho lokálního repozitáře; nejsou automaticky lepší pro každou automatizaci nebo izolované prostředí.

Pull request ani CI se použitím worktree nemění. Worktree organizuje lokální pracovní adresáře. Review, vzdálené větve, oprávnění a automatické kontroly dál řeší hostingová služba a CI/CD.

Bezpečný pracovní postup

Před odstraněním ověř stav a uklízej přes Git.

Worktree zjednodušuje přepínání kontextu, neodpouští ale necommitnuté soubory ani konfliktní lokální prostředí.

před přidáním ověř výchozí commit a použij výslovný název nové větve
kontroluj přehled pomocí git worktree list a stav v konkrétním adresáři pomocí git -C <cesta> status
počítej s kolizemi portů, názvů kontejnerů, lokálních databází, souborů .env a build výstupů
linked worktree odstraň až po commitu nebo vědomém zachování potřebné práce
pokud adresář zmizel ručně, nejprve prohlédni git worktree prune --dry-run a teprve potom ukliď osiřelá metadata
důležité commity publikuj do vzdáleného repozitáře; samotný worktree není záložní kopie

Časté otázky

Git Worktrees bez častých záměn.

Je linked worktree nový Git repozitář?

Ne. Je to další pracovní adresář připojený ke stejnému repozitáři. Sdílí jeho objekty, běžné refs a většinu konfigurace, ale má vlastní HEAD, index a checkoutnuté soubory.

Je worktree totéž co branch?

Ne. Branch je reference na commit, worktree je pracovní adresář s checkoutem. Při přidání worktree může Git novou branch vytvořit, ale oba pojmy zůstávají oddělené.

Může být stejná větev checkoutnutá ve více worktrees?

Git to ve standardním workflow odmítne, protože by dva pracovní adresáře mohly posouvat stejnou branch. Každému worktree proto běžně přiřaď vlastní větev nebo použij detached HEAD pro dočasné čtení a testování.

Co udělá git worktree remove?

Odstraní linked pracovní strom a jeho administrativní vazbu. Bez force odmítne worktree s upravenými či nesledovanými soubory; samotnou branch ani její commity tím nemaže.

Kdy použít git worktree prune?

Když pracovní adresář už chybí a v repozitáři po něm zůstala osiřelá metadata. Pro běžné ukončení práce použij remove a před prune můžeš bezpečně zkontrolovat výsledek volbou --dry-run.

Osobní zkušenost

Více pracovních stromů používám pro oddělené a ověřitelné změny.

Při práci na PHP aplikacích kombinuji Git workflow s testy a review tak, aby rozpracovaná feature neblokovala rychlou opravu ani kontrolu jiné větve.

Zobrazit moje znalosti Nezávazně probrat projekt

Oficiální dokumentace git worktree