From 7808eb96a3d1c856a60527d21ace600ccaa1f0c3 Mon Sep 17 00:00:00 2001 From: lachtan Date: Sun, 20 Sep 2026 14:14:28 +0200 Subject: [PATCH] nanobot: 2026-09-20 14:13:22 --- .../2026-09-20_git-worktrees-guide.md | 270 ++++++++++++++++++ 1 file changed, 270 insertions(+) create mode 100644 projects/devops/artifacts/2026-09-20_git-worktrees-guide.md diff --git a/projects/devops/artifacts/2026-09-20_git-worktrees-guide.md b/projects/devops/artifacts/2026-09-20_git-worktrees-guide.md new file mode 100644 index 0000000..a0ca523 --- /dev/null +++ b/projects/devops/artifacts/2026-09-20_git-worktrees-guide.md @@ -0,0 +1,270 @@ +# Git worktrees — praktická učebnice + +*Zdroje: `git-scm.com/docs/git-worktree`, VS Code docs (branches-worktrees, 9/16/2026), Claude Code docs (worktrees). Vše ověřeno fetchem 2026-09-20.* + +--- + +## 1. Co worktree je (mental model) + +- Jedna repository (jeden `.git` adresář, jedna historie, branches, tags, remote) — **několik working directories**. +- **Primary worktree** = klasický checkout. **Linked worktree** = další adresář, který sdílí tu samou historii, ale má vlastní soubory, staging area a vlastní checked-out branch. +- Git **zakazuje mít jeden branch checkoutnutý ve dvou worktrees zároveň** — konflikt je vyloučen konstrukcí. +- Sdílené: historie, branches, tags, remotes, `.git/config`, stash. +- Nesdílené: soubory na disku, index, uncommitted changes. +- Nesrovnávat s clone: worktree nespotřebuje druhou kopii historie (hardlinked objects), nemá vlastní remote fetch, jeden `git fetch` platí pro všechny. +- Praktický důsledek: **gitignorované soubory se v novém worktree NEduplikují** — `.env`, `node_modules`, build outputy tam nejsou. Řešení viz níže. + +--- + +## 2. CLI — kompletní kuchařka + +### Základní lifecycle + +```bash +# výpis +git worktree list +# /home/user/proj a1b2c3d [main] <- primary +# /home/user/proj-wt-fix e4f5g6h [fix/leak] <- linked + +# nový worktree na nové branch (typicky hlavní užití) +git worktree add ../proj-fix -b fix/leak + +# nový worktree na existující branch +git worktree add ../proj-main main # pozor: musí být volná (nesmí být checkoutnutá jinde) + +# detachnutý (na konkrétním commitu, bez branch) +git worktree add ../proj-hotfix +``` + +### Konvence umístění + +Dvě osvědčené školy: + +1. **Vedle repa** (`../proj-fix`, `../proj-auth`) — vhodné, když chceš každý worktree otevřít v jiné instanci editoru/IDE. +2. **Pod jedním rodičovským adresářem pro worktrees** (`../proj/.worktrees/` nebo `~/worktrees/proj/`), primární checkout zůstává čistý. Pozn.: Claude Code umísťuje své worktrees do `.claude/worktrees//` uvnitř repa. +3. (Pozor na `.gitignore` — worktree adresáře uvnitř repa musí být ignorované, jinak se Git snaží trackovat jejich obsah.) + +### Denní provoz + +```bash +cd ../proj-fix # pracuj úplně normálně +git status # funguje, vidí jen tenhle worktree +git add -A && git commit -m "fix" +git push -u origin fix/leak # sdílený remote, funguje +``` + +### Úklid + +```bash +# bezpečné odstranění (odmítne, pokud jsou uncommitted změny) +git worktree remove ../proj-fix + +# s násilím (zneužívej vědomě) +git worktree remove --force ../proj-fix + +# worktree už je smazaný ručně (rm -rf) -> vyčistit admin metadata +git worktree prune +``` + +### Když to spadne (recovery) + +- **Branch zůstala po remove viset** — branch nezávisí na worktree; smaž ji klasicky: `git branch -d fix/leak` (nebo `-D` pro nemergenutou). +- **`git worktree list` ukazuje mrtvé worktrees** → `git worktree prune` (git je nakonec pročistí sám dle `gc.worktreePruneExpire`, výchozí ~3 měsíce). +- **Nemůžeš checkoutnout branch** (`already checked out in ...`) → je checkoutnutá v jiném worktree: buď tam pokračuj, nebo tam dáš `git switch` jinam, nebo `git worktree add --force` (riskantní — stejná branch na dvou místech pak může divergovat). +- **Chceš zjistit, v čem je rozdíl oproti main** → vše funguje standardně: `git diff main...fix/leak`, `git log main..fix/leak`. + +### LVM/Zabbix tipy pro homelab kontext + +- worktrees sdílejí `.git` přes hardlinky → **dvě kopie velkého repa na disku netvoří** (přesto, `du -sh` počítá hardlinky dřív jen jednou — na velkých repos zkontroluj `du -sh --apparent-size`). +- `git gc` a `git worktree prune` v primary worktree spravují metadata všech linked worktrees. +- **Změna commitu v primary neovlivní soubory v linked worktree** — na testování dvou verzí side-by-side ideální. + +### Vzorce pro denní použití + +| Chci | Příkaz | +|---|---| +| Paralelně: hotfix do main + feature | `git worktree add ../proj-hotfix -b hotfix/prod-quirk` | +| Code review v čistém stavu | `git worktree add ../proj-review origin/pr-42` | +| Spustit starou verzi (demo/debug) | `git worktree add ../proj-v1.0 v1.0` | +| Bisect bez ztráty workspace | `git worktree add ../proj-bisect` (detached) | + +--- + +## 3. VS Code — built-in podpora (ne extension) + +VS Code má **nativní podporu worktrees** — Source Control view → Repositories → kontext menu repa → **Worktrees → Create Worktree**. + +### Postup vytvoření + +1. Otevři Source Control view (`Ctrl+Shift+G`). +2. Rozbal **Repositories** sekci (je-li skrytá, přes `...` menu view). +3. Reprodukovatelně: klikni na repozitář → `...` (More Actions) → **Worktrees → Create Worktree**. +4. Dialog: vyber branch + zadefinuj cestu (VS Code složku vytvoří a branch do ní checkoutne). +5. Nový worktree se objeví jako **samostatná položka v Repositories view**. + +### Otevírání a switch + +- Každý worktree otevřeš jako samostatnou složku = **samostatné VS Code okno** (doporučeno; každé okno má vlastní terminál, debug, problems). +- Cesty: `File → Open Recent` pro rychlý přístup; v Repositories view pravým na worktree → **Open Worktree in New Window / Current Window**; Command Palette: `Git: Open Worktree in New Window`. +- VS Code automaticky pozná, že otevřená složka je worktree (čte `.git` file → gitdir pointer). + +### Nastavení, které se vyplatí + +```jsonc +// settings.json +{ + // kopírovat gitignorované soubory do nového worktree (glob patterns) + "git.worktreeIncludeFiles": [".env", "node_modules/**"], + + // automaticky detekovat worktrees vytvořené mimo VS Code (např. z CLI) + "git.detectWorktrees": true, + "git.detectWorktreesLimit": 50 // default +} +``` + +- `git.worktreeIncludeFiles` — glob; soubor se zkopíruje **jen pokud matchne pattern A je gitignorovaný**. Typické: `.env`, `node_modules/**` (ušetří reinstall), `venv/**` pozor na absolutní cesty ve scripthích (activate skripty obsahují absolutní cesty — radši nový venv). +- `git.detectWorktrees` — pokud worktrees zakládáš z CLI, zapni; jinak VS Code vidí jen ty vytvořené přes GUI. + +### Další GUI schopnosti + +- **Compare with Workspace** — pravým na změněný soubor v worktree → diff oproti hlavnímu workspace, side-by-side. +- **Migrate Worktree Changes** (Command Palette) — zmerguje všechny změny z worktree do aktuálního workspace. + +### Gotchas + +- Multi-root workspace se všemi worktrees v jednom okně je technicky možný, ale search/Go-to-Definition ti bude míchat cesty — **preferuj jedno okno per worktree**. +- Search (`Ctrl+Shift+F`) jede na workspace složku, ne na repozitář — nečte automaticky worktrees mimo otevřenou složku. +- `git.worktreeIncludeFiles` neřeší `.env` typu "každý worktree jiný" — to je pořád ruční práce. + +--- + +## 4. Claude Code — `--worktree` / `-w` (v2.1.49+) + +### Založení izolované session + +```bash +cd ~/src/repo +claude --worktree fix-leak # nebo -w fix-leak +# -> vytvoří .claude/worktrees/fix-leak/ +# na branchi worktree-fix-leak (z remote default branch, typicky origin/main) + +claude -w fix-leak -p "..." # non-interactive; -p přeskočí trust dialog +``` + +- Další terminál + jiné jméno = druhá paralelní session. Bez jména vygeneruje náhodné (typicky `bright-running-fox` styl). +- **Interactive mód vyžaduje workspace trust** — poprvé v adresáři spusť `claude` bez flagů a přijmi trust dialog, jinak `--worktree` spadne na erroru. `-p` (headless) trust check nedělá. +- Uvnitř session můžeš Claude říct "work in a worktree" → použije nástroj `EnterWorktree` (před vstupem do worktree mimo `.claude/worktrees/` se ptá na approval). + +### Co je uvnitř a co chybí + +- Worktree = **fresh checkout** (tracked soubory) — `.env`, `node_modules`, build cache ne. Řešení: + - nechat Claude nainstalovat závislosti v worktree, + - nebo přidat **`.worktreeinclude`** do rootu repa (syntaxe `.gitignore`; kopíruje jen soubory, které matchnou pattern **a** jsou gitignorované). + ```gitignore + # .worktreeinclude + .env + .env.local + config/secrets.yaml + ``` + - Pozor na `**/` patterny u adresářů ignorovaných jako celek — radši pojmenuj adresář v patternu (`vendor/**/config.json` místo `**/config.json`). + +### Cleanup a resume + +- Při exitu interactive session Claude kontroluje worktree na změny: **čistý** → smaže worktree i branch (named session se předtím zeptá); **špinavý** (změny/untracked/commity) → prompt keep/remove. **Remove smaže i branch i veškerou práci v ní** — neodpovídej automatikou. +- `-p` (headless) cleanup nedělá — worktrees čistí až periodic sweep (dle `cleanupPeriodDays`) nebo ručně `git worktree remove`. +- `--continue` / `--resume` vrací session **zpět do jejího worktree**; `--fork-session` zůstává v launch adresáři. Deleted worktree → session se obnoví v launch adresáři. +- Resume z jiného worktree nebo z podadresáře worktree může selhat — **resumuj z main checkoutu**. + +### Isolation enforcement (proč to je bezpečné) + +Claude Code v izolované session blokuje: +1. **File edits** (`Edit`/`Write`/`NotebookEdit`) do main checkoutu. +2. **Commands s working directory v main checkoutu**. +3. **Git redirecty** (`git -C`, `--git-dir`, `GIT_DIR`/`GIT_WORK_TREE`, `cd` do main checkoutu). +4. **Nepřehledné commandy** (dynamicky sestavené git příkazy, které nelze staticky ověřit). + +Platí pro session i všechny její subagenty, interaktivně i v backgroundu. **Vypnout se nedá.** + +### Konfigurace + +| Setting | Hodnota | Význam | +|---|---|---| +| `worktree.baseRef` | `"fresh"` (default) | Branch z remote default branch (typicky `origin/main`) | +| | `"head"` | Branch z aktuálního lokálního `HEAD` (in-progress práce) | + +- Nelze zadat konkrétní branch jménem — na to je `git worktree add` ručně (viz Manage worktrees manually). +- **PR checkout**: `claude -w "#42"` nebo `claude -w "https://github.com/org/repo/pull/42"` (i GitLab MR URL). Worktree vznikne na `.claude/worktrees/pr-42`, branch z head commitu PR. +- Opětovné použití jména: existující adresář otevře místo vytvoření nového; za jistých podmínek (čistý, na své branchi, merged PR) resetuje na default branch, jinak pokračuje od starého tipu. + +### Subagent isolation + +- Řekni "use worktrees for your agents" → každý subagent dostane vlastní worktree. +- Trvale pro custom subagenta: frontmatter `isolation: worktree` v `.claude/agents/.md`. +- Subagent worktree se automaticky odstraní, když subagent skončí bez změn; se změnami zůstává, dokud ho sweep (dle `cleanupPeriodDays`) nemůže bezpečně smazat. +- Během běhu agenta drží Claude Code na worktree `git worktree lock`, aby ho souběžný cleanup nesmazal. + +### Sdílené prostředí s main checkoutem + +- `.git` adresář (git commit z worktree funguje i se sandboxem), project-scope pluginy, uložené permission approvals (`settings.local.json`). + +### Troubleshooting (nejčastější) + +- **LFS / filter drivery**: `git lfs install --local` zapisuje filter do repo `.git/config` → v worktree jsou LFS pointer files místo obsahu. Fix: v worktree `git lfs pull`, preventivně používej globální `git lfs install` (bez `--local`). +- **Symlinky na `.claude`, `.claude/worktrees` nebo worktree path** → worktree creation odmítnut (bezpečnost). +- **`Refusing to use as an isolation worktree`** → git metadata adresáře resolvovala do main checkoutu (typicky špatný `.git` pointer); řeš dle textu erroru. +- **`includeIf` v repo `.git/config`** blokuje tvorbu worktree — přesuň nastavení přímo do configu. +- **Network path worktree** (NFS/SMB) → nikdy se do něj nerresumuje. + +--- + +## 5. Kombinace workflow: CLI + VS Code + Claude Code + +Typický den s jedním repem `proj`: + +``` +~/src/proj # primary, main branch, VS Code okno A +~/src/proj-fix # linked worktree, fix/leak, VS Code okno B (vytvořeno GUI) +~/src/proj/.claude/worktrees/ # Claude Code sessions (feature-x, pr-42, ...) +``` + +```bash +# ráno: hotfix a feature paralelně +git -C ~/src/proj worktree add ../proj-fix -b fix/leak +code ../proj-fix # VS Code okno B + +# feature paralelně přes Claude Code (jiný terminál) +claude -w feature-auth + +# večer: úklid +git worktree remove ../proj-fix # po merge do main +claude # v interactive session exit -> cleanup prompt +``` + +### Rozdělení rolí + +| Nástroj | Kdy | +|---|---| +| **CLI `git worktree`** | Plná kontrola (konkrétní branch, umístění mimo repo, bisect, srovnávání verzí) | +| **VS Code GUI** | Rychlé vytvoření/otevření, diff worktree vs. workspace (`Compare with Workspace`), `Migrate Worktree Changes` | +| **Claude Code `-w`** | Paralelní AI session bez rizika kolize editů; PR review (`-w "#42"`) | + +### Pravidla, na která se vyplatí držet + +1. **Jeden worktree = jeden úkol = jedna branch**. Nesdílej worktree mezi dvěma tasky. +2. **Merge řeš v primary checkoutu**, ne v worktree — tam jen commit a push. +3. **Po skončení tasku worktree odstraň** — worktrees se hromadí rychleji, než člověk čeká (`git worktree list` ať je pravidelný reflex). +4. **`.worktreeinclude` / `git.worktreeIncludeFiles` nastav hned u repa**, kde `.env`/deps potřebuješ — neaž při prvním kopnutí do stěny. +5. Venv/deps s absolutními cestami (venv, node_modules symlinkované) do worktree necopyuj — vytvoř nové. +6. **Claude Code worktree nemaž ručně, dokud session žije** — drží na něm lock; sweep/exit ho uklidí sám. + +--- + +## 6. Cvičení (udělej na play repu) + +1. `git init /tmp/wt-play && cd /tmp/wt-play && echo a > f && git add . && git commit -m init` +2. `git worktree add ../wt-play-fix -b fix/x` — uprav `f`, commit v worktree; `cd` zpět do primary — soubor se nezměnil (sdílená historie, ne soubory). +3. `git worktree list` — najdi oba. +4. Zkus checkoutnout `fix/x` v primary → git odmítne (already checked out). Správná cesta: pracuj v worktree. +5. `git worktree remove ../wt-play-fix && git branch -d fix/x` +6. VS Code: vytvoř worktree přes Source Control GUI, otevři v novém okně, vyzkoušej `Compare with Workspace`. +7. Claude Code (na reálném repu s trustem): `claude -w test-wt`, nech něco změnit, exit → sleduj cleanup prompt. \ No newline at end of file