Git Worktree — paralelní práce s gitem
git-tools:git-worktree).
Zobrazit zdroj na GitHubu →Co je git worktree
git worktree přidá k repozitáři druhý pracovní adresář s vlastní větví. Původní checkout zůstane tak, jak je — včetně necommitnutých změn — a vedle něj vznikne čistý adresář pro jiný úkol. Žádné stashování, žádné riziko, že se rozpracované změny jednoho úkolu promíchají s druhým. Pro běžnou práci s gitem viz Git
, pro větvící model Gitflow viz Git Flow
.
Kdy ho použít
- Oprava chyby ve chvíli, kdy je rozpracovaná jiná funkce, které se nesmí dotknout
- Souběžná práce na dvou větvích (např. dva agenti nebo dvě terminálové session nad stejným repozitářem)
- Revize cizího pull requestu bez přepínání vlastní větve
- Izolované, jednorázové experimenty, které nemají zasahovat do hlavního checkoutu
- Dlouhý build nebo testy na jedné větvi, zatímco na druhé pokračuje vývoj
Základní příkazy
git worktree list # všechny worktree a jejich větve
git worktree add ../repo-hotfix hotfix/login # checkout existující větve do nového adresáře
git worktree add -b fix/login ../repo-fix origin/main # nová větev z origin/main
git worktree add --detach ../repo-test v1.4.0 # bez větve, jen na prohlédnutí tagu
git worktree remove ../repo-fix # smazat worktree (větev zůstává)
git worktree prune # uklidit záznamy po ručně smazaných adresářích
git worktree lock ../repo-fix # chránit před prune (např. na odpojeném disku)
git worktree move ../repo-fix ../fix-login # přesunout adresář
Postup: hotfix vedle rozpracované práce
# 1. Jste uprostřed práce na feature/checkout, do toho přijde chyba v produkci
git fetch origin
git worktree add -b hotfix/cart-total ../shop-hotfix origin/main
# 2. Oprava v novém adresáři — původní checkout se nezměnil
cd ../shop-hotfix
composer install # závislosti si worktree instaluje sám
# ... oprava, testy ...
git commit -am "fix: zaokrouhlení součtu košíku"
git push -u origin hotfix/cart-total
# 3. Po sloučení úklid
cd ../shop
git worktree remove ../shop-hotfix
git branch -d hotfix/cart-total
Kam worktree umístit
Dvě běžné konvence:
- Vedle repozitáře (
../repo-<úkol>) — nic nepřekáží v pracovním stromu, hodí se pro jednotlivce. - Uvnitř repozitáře (
.worktrees/<úkol>) — vše na jednom místě, hodí se pro agenty a skripty. Adresář musí být v.gitignore, jinak se objeví vgit status.
Držte jednu konvenci a pojmenovávejte podle úkolu nebo čísla ticketu; po měsíci je ../repo-2 k ničemu.
Časté chyby
| Chyba | Co se stane | Řešení |
|---|---|---|
Smazání adresáře přes rm -rf | Git si worktree dál pamatuje a větev v něm drží jako checkoutnutou | git worktree prune, příště git worktree remove |
| Checkout větve, která je otevřená jinde | fatal: '<větev>' is already used by worktree at … | git worktree list, pracovat tam nebo založit novou větev přes -b |
| Očekávání nainstalovaných závislostí | Nový worktree nemá vendor/, node_modules/ ani .env — nejsou v gitu | Spustit instalaci v novém adresáři, .env zkopírovat |
| Dva worktree nad stejnou databází nebo portem | Migrace a testy si navzájem přepisují data, druhý server nenastartuje | Vlastní databáze a port pro každý worktree, nebo testy pouštět jen z jednoho |
| Zapomenuté worktree | Zabírají místo a blokují mazání větví | Pravidelně git worktree list, po merge hned remove |
| Submoduly | V novém worktree jsou prázdné | git submodule update --init v novém adresáři |
git worktree remove se změnami | Git odmítne smazat worktree s necommitnutou prací | Commitnout, nebo vědomě --force |
Worktree a AI agenti
Dva agenti nad jedním checkoutem si přepisují soubory a commitují cizí změny. Worktree dává každému vlastní adresář a větev, takže běží souběžně a výsledky se potkají až v pull requestu. Stejné pravidlo platí pro dvě terminálové session jednoho člověka.
Zdroj
Tento postup existuje i jako instalovatelná dovednost pro Claude Code. Udržovaná verze — včetně přesných příkazů a okrajových případů — žije v pluginu git-tools
v repozitáři siva01c/claude-plugins
.
Časté otázky
Co je git worktree?
Worktree je další pracovní adresář téhož repozitáře s vlastní checkoutnutou větví. Všechny worktree sdílejí jednu historii a jedno .git, takže se nic neklonuje znovu a commit z jednoho je hned vidět v ostatních.
Jaký je rozdíl mezi git worktree a git clone?
Klon je samostatný repozitář s vlastní kopií historie, který se s původním synchronizuje přes push a pull. Worktree je jen další checkout stejného repozitáře: zabere místo pracovních souborů, vznikne za okamžik a větve i commity má společné.
Kdy použít worktree místo git stash?
Stash stačí na pár minut. Jakmile má druhá práce trvat déle, běžet souběžně (dlouhý build, testy, druhý agent) nebo se k rozdělané práci budete vracet, je worktree bezpečnější — nic se neodkládá a obě větve zůstanou rozpracované vedle sebe.
Jak worktree smazat?
git worktree remove <cesta> smaže adresář i záznam o něm. Pokud jste adresář smazali ručně, záznam uklidí git worktree prune. Větev zůstává; tu smaže až git branch -d <větev>.
Proč git hlásí, že větev je už checkoutnutá?
Jedna větev může být v jednu chvíli checkoutnutá jen v jednom worktree. git worktree list ukáže ve kterém. Buď pracujte tam, nebo si založte novou větev přes git worktree add -b <nová-větev> <cesta> <výchozí-bod>.