Worktree

Co skill dělá

Zapíná a ruší worktree layout projektu – uspořádání, ve kterém adresář projektu není pracovní adresář, ale kontejner s jedním holým repozitářem (.bare) a několika pracovními adresáři, jeden na každou rozdělanou větev. Díky tomu může nad projektem běžet víc Claude session naráz, aniž si přepisují soubory.

Pravidla provozu layoutu drží ~/.claude/standards/worktree.md – kde co leží, jak se zakládá a dokončuje větev, proč se v main/ nepracuje a proč v kořeni kontejneru nefunguje git. Skill je nevlastní, jen si je importuje do rozcestníku v kořeni kontejneru, aby platila v každé session projektu. Stojí v kořeni ~/.claude vedle ~/.claude/standards/rules.md a structure.md schválně: čte je většina skillů i preflight.md, tedy i ten, kdo tenhle skill nainstalovaný nemá. Ta cesta je závazné rozhraní a nesmí se měnit tiše.

Co skill nedělá

• Nezakládá větve a nemerguje. Zakládání větve je běžná práce podle pravidel v ~/.claude/standards/worktree.md a převzetí lokálního stavu do ní vykonává globální git hook githooks/post-checkout, ne režim skillu; dokončení větve vede /merge (~/.claude/skills/merge/SKILL.md), protože platí i v projektu bez tohohle layoutu. Skill, který bys musel volat pokaždé, když zakládáš větev, by byl horší než pravidlo, které prostě platí.
• Nezakládá projekt. Celé nastavení projektu včetně volby layoutu vede /project, který si tenhle skill volá jako jeden ze svých kroků. Tenhle skill je přepínač pro adresář, který už existuje.
• Nerozhoduje, jestli se layout hodí. To je volba uživatele; /project se na ni ptá, skill ji jen provede.
• Necommituje. Kontejner není pracovní strom a nic v něm ve gitu není. Změny v main/ po konverzi zůstanou tak, jak byly.

Fáze 0 – Příprava

Společný začátek je v ~/.claude/skills/preflight.md; platí z něj bod 1 – kořen projektu. Body 3 až 5 neplatí: skill nesahá na kód a stav pracovního stromu ani průběžná kontrola jeho běh neovlivní.

Tři vlastní odchylky:

• Detekci dělej výhradně přes Glob, ne git přes Bash – nenulový návratový kód by vyrobil červenou chybu a zbytečně vyděsil uživatele. Vlastní přeskládání pak Bashem.
• Chybějící .git není důvod skončit. Příprava u ostatních skillů říká „není-li to repozitář, skonči“; tady je prázdný adresář legitimní vstup režimu enable, který v něm založí nový projekt.
• Bod 2 – projektový CLAUDE.md – neplatí. Skill do něj nezapisuje a nic z něj nepotřebuje; hlavně by ale jeho blokující pokyn „chybí-li ## Kontrakt příkazů a projekt má kód, zastav se“ zastavil enable nad prázdným adresářem, kde žádný projektový soubor ještě není. Rozcestník v kořeni kontejneru je jiný soubor a zapisuje se až v fázi 2.

Fáze 1 – Zjisti stav

Stav nese tvar adresáře, ne zápis v souboru – nemůže se tedy rozejít s realitou a nic dalšího se ověřovat nemusí:

Stojíš-li v podadresáři, jdi po ~/.claude/standards/worktree.md, Jak si skill najde projektový adresář, nahoru ke kontejneru – jinak bys layout zapínal uvnitř layoutu.

Fáze 2 – Proveď režim

status (nebo žádný argument)

Vypiš, jestli je layout zapnutý. Je-li, vypiš i git -C <container> worktree list a git -C <container> branch -a – tedy co je rozdělané a jaké větve existují. Worktree, o kterém uživatel nejspíš neví, zmiň zvlášť; nemaž ho.

enable

Je-li layout už zapnutý → jen to oznam, nic neměň. Jinak podle nálezu z fáze 1:

Nový projekt (adresář bez .git):

git init --bare .bare
printf 'gitdir: ./.bare\n' > .git
git worktree add main -b main

Konverze existujícího repozitáře. Přeskládává se .git, takže dva kroky před tím jsou povinné a žádný se nevynechává:

1. Ověř git status – necommitnuté nebo nepushnuté změny nejdřív vyřeš.
2. Řekni nahlas, že jde o přeskládání adresáře, a nech si to potvrdit (AskUserQuestion).

Zálohou je tu přejmenovaný původní adresář – mv na .migrating nechá všechny pracovní soubory na místě a bere si z něj jen .git, takže se nekopíruje nic navíc:

mv <project> <project>.migrating
mkdir <project>
mv <project>.migrating/.git <project>/.bare
git --git-dir=<project>/.bare config core.bare true
printf 'gitdir: ./.bare\n' > <project>/.git
git -C <project> worktree add main main
rm -f <project>/.bare/index <project>/.bare/COMMIT_EDITMSG

Ten rm -f není kosmetika: bare repo svůj index nikdy nepoužívá, ale po původním pracovním adresáři tam zůstane zamrzlý na posledním commitu před konverzí a git diff --cached z něj pak trvale hlásí smyšlené změny.

Ověř, že se nic neztratilo, a teprve pak smaž zálohu:

diff -r <project>.migrating <project>/main --exclude=.git   # musí být prázdné
rm -rf <project>.migrating

Netrackované a gitignorované soubory (.env, node_modules) přesuň do main/ – je to jejich kanonické místo. CLAUDE.md, README.md a docs/ v konverzi zůstávají v main/, kde jsou po worktree add už samy od sebe.

V obou případech nakonec zapiš do kořene kontejneru rozcestník CLAUDE.md – a nic víc:

# <Název projektu>

Tenhle adresář není projekt, ale kontejner s worktree layoutem. Pravidla práce s ním:

@~/.claude/standards/worktree.md

Vlastní pravidla projektu jsou v `main/CLAUDE.md` a importují se odsud:

@main/CLAUDE.md

## Odchylky

- <odchylky konkrétního projektu od postupu výš, nebo že žádné nejsou>

U konverze je typický omyl nechat v kořeni původní CLAUDE.md – ten se přesunul do main/ spolu se zbytkem repozitáře a je správně tam; v kořeni vzniká nový, netrackovaný rozcestník. Pravidla projektu do rozcestníku nikdy nekopíruj: dvě kopie se rozejdou a načtou se obě.

disable

Není-li layout zapnutý → jen to oznam, nic neměň. Jinak nejdřív dvě zastávky, obě blokující:

1. git -C <container>/main worktree list musí hlásit jen main. Zbyla-li rozdělaná větev, skonči a řekni to – slití nebo zahození větve je rozhodnutí uživatele, ne skillu.
2. git -C <container>/main status --porcelain musí být prázdný.

Pak si zapamatuj větev (git -C <container>/main rev-parse --abbrev-ref HEAD), nech si přeskládání potvrdit a pořiď zálohu, kterou už dál nerozebereš – na rozdíl od enable, kde zálohou je přejmenovaný původní adresář, se tady hýbe vším naráz:

cp -c -R <container> <container>.backup           # na APFS instantní; jinde bez -c

# 1) z main/ udělej samostatný repozitář
rm -f <container>/main/.git                       # soubor "gitdir: …", má absolutní cestu
mv <container>/.bare <container>/main/.git
git -C <container>/main config core.bare false
git -C <container>/main symbolic-ref HEAD refs/heads/<branch>
git -C <container>/main worktree prune            # zapomeň registraci zrušeného worktree
git -C <container>/main reset                     # obnov index z HEAD, pracovní strom nech být

# 2) přenes lokální stav kontejneru dovnitř
mv <container>/.claude/* <container>/main/.claude/   # cíl nejdřív vyrob: mkdir -p
rm -f <container>/CLAUDE.md <container>/.git      # rozcestník a ukazatel na .bare

# 3) povyš main/ na projekt
mv <container>/main <container>.new
rmdir <container>                                 # musí projít – zbylo-li něco, zastav se
mv <container>.new <container>

rmdir je pojistka, ne úklid. Projde jen nad prázdným adresářem, takže selže právě tehdy, když v kontejneru zbylo něco, o čem tenhle postup neví – nepoužívej místo něj rm -rf a zastav se a ukaž uživateli, co tam leží.

.git v main/ je soubor s absolutní cestou do .bare/worktrees/main, takže přesun ho rozbije – proto se maže a nahrazuje adresářem. symbolic-ref je nutný, protože HEAD bare repozitáře ukazuje jinam než HEAD zrušeného worktree.

.claude/settings.local.json se stěhuje z kořene kontejneru, kde dosud žil; kdyby zůstal, zmizel by s ním – jsou v něm hooky a povolení, tedy netrackovaný stav, který nikde jinde není. Přesouvej obsah, ne adresář: projekt může mít vlastní trackované main/.claude/CLAUDE.md, a mv celého adresáře by v tom případě tiše vyrobil main/.claude/.claude/ a uspěl.

Ověř a teprve pak uklízej:

git -C <container> status                         # správná větev; jediný netrackovaný
                                                  # přírůstek smí být .claude/, který
                                                  # jsi tam právě přenesl
diff -r <container>.backup/main <container> --exclude=.git --exclude=.claude
rm -rf <container>.backup

Záloha se během přeskládání nerozebírala, takže diff -r má proti čemu běžet. .claude se z porovnání vynechává schválně – v záloze leží v kořeni, v novém projektu uvnitř.

Časté chyby

• Zapnout layout uvnitř layoutu. Stojíš-li ve worktree větve, .git je soubor a .bare vedle něj není – vypadá to jako obyčejný repozitář. Proto se ve fázi 1 jde nahoru ke kontejneru, ne jen do prvního adresáře s .git.
• Nechat pravidla projektu v kořeni kontejneru. Kontejner není pracovní strom: nic v něm není ve gitu, nikdy to nepůjde commitnout a zmizí to s adresářem.
• Smazat zálohu před diff -r. U disable je záloha jediná cesta zpátky – hýbe se vším naráz. U enable je to jinak: git data leží v novém .bare a pracovní soubory v .migrating, takže se dá obnovit obojí i bez kopie navíc.

Fáze 3 – Závěr

Oznam výsledný stav a co jsi kvůli němu změnil – u enable a disable i to, kde leží záloha a že jsi ji po ověření smazal. Zůstala-li záloha ležet, protože ověření neprošlo, řekni to jako první, ne až na konci výpisu.

Zakonči jednou z těchto vět, nikdy ničím vágním mezi tím:

• Worktree layout je v projektu <jméno> <zapnutý|vypnutý> a ověřený, můžeš pracovat dál.
• Přepnutí hotové není – brání tomu: <konkrétní seznam>.