Równoległy development z Git Worktree

Jesteś w połowie pracy na feature branchu, gdy wpada raport o błędzie P0. Musisz zbadać go i naprawić natychmiast, ale stashowanie pracy w toku grozi utratą kontekstu, a przełączanie branchy niszczy twoje node_modules i cache build. Git worktree rozwiązują ten problem dając ci wiele niezależnych checkoutów tego samego repozytorium, a aplikacja Codex czyni worktree pełnoprawnym elementem workflow.

Czego się nauczysz

• Kompletny workflow do uruchamiania, pracy i mergowania wątków opartych na worktree w Codex
• Jasne kryteria decyzyjne dla wyboru “Work on the worktree” vs “Sync with local”
• Strategie uruchamiania wielu agentów równolegle na tym samym codebase’ie bez konfliktów
• Praktyki czyszczenia i zarządzania dyskiem zapobiegające rozrostowi worktree

Jak działają worktree w Codex

Gdy uruchamiasz wątek Worktree w aplikacji Codex, Codex tworzy Git worktree w $CODEX_HOME/worktrees. Worktree startuje na commit HEAD dowolnego brancha, który wybierzesz, i zaczyna w stanie detached HEAD — bez zanieczyszczania branchy. Twój lokalny checkout pozostaje nienaruszony.

Każdy worktree ma własną kompletną kopię plików repozytorium. Współdzielą te same metadane .git (commity, branche, refy), ale każdy ma niezależne drzewo robocze, indeks i HEAD. To oznacza, że Codex może uruchamiać testy, instalować zależności i edytować kod w jednym worktree, podczas gdy ty kontynuujesz pracę w innym.

Notatka

Worktree wymagają repozytorium Git. Jeśli twój projekt nie jest pod kontrolą wersji, automatyzacje uruchamiają się bezpośrednio w katalogu projektu, a tryb Worktree jest niedostępny.

Workflow dwóch ścieżek

Po zakończeniu pracy Codex na worktree masz dwie opcje obsługi wyników:

Ścieżka 1: Praca na worktree

Najlepsza, gdy możesz zweryfikować zmiany bezpośrednio na worktree (np. twój lokalny skrypt setup środowiska instaluje wszystkie zależności).

1. Kliknij Create branch here w nagłówku wątku, żeby zamienić detached HEAD w nazwany branch.
2. Użyj wbudowanego terminala lub przycisku “Open”, żeby uruchomić IDE wskazujące na worktree.
3. Uruchom testy, zweryfikuj zmiany i iteruj follow-up promptami.
4. Commituj, pushuj i twórz PR bezpośrednio z aplikacji Codex.
5. Opcjonalnie “Add to sidebar”, żeby promować worktree do stałego miejsca pracy.

Ścieżka 2: Synchronizacja z lokalnym

Najlepsza, gdy potrzebujesz zmian w swoim głównym checkout (np. możesz uruchomić tylko jedną instancję dev servera).

1. Kliknij Sync with local w nagłówku wątku.
2. Wybierz utworzenie nowego brancha lub synchronizację z istniejącym.
3. Wybierz metodę synchronizacji:
   • Apply: Oblicza zmiany od najbliższego współdzielonego commita i aplikuje je jako patch, zachowując twoją lokalną historię commitów.
   • Overwrite: Sprawia, że twój lokalny checkout dokładnie odpowiada worktree, zastępując lokalne pliki i historię commitów.
4. Rozwiąż ewentualne konflikty, jeśli twój lokalny checkout się rozjechał.
5. Zweryfikuj zmiany w swoim lokalnym środowisku.

Prompt: Podział feature'a na równoległe wątki worktree

Otwórz trzy wątki Worktree, każdy bazujący na tym samym branchu main:

Wątek 1: “Implement the new /api/v2/users endpoint following the patterns in src/routes/v1/users.ts. Include request validation with Zod and add unit tests.”

Wątek 2: “Create the database migration for the users_v2 table. Add the Drizzle schema, migration file, and seed data. Run the migration locally to verify.”

Wątek 3: “Update the OpenAPI spec in docs/openapi.yaml to include the v2 users endpoints. Generate the TypeScript client with openapi-typescript.”

Następnie zsynchronizuj wszystkie trzy do tego samego feature brancha używając “Apply”, żeby ułożyć zmiany warstwowo.

Wiele worktree, jeden feature branch

Potężny wzorzec polega na synchronizowaniu wielu wątków worktree do tego samego feature brancha. Każdy wątek obsługuje inny aspekt pracy, a ty aplikujesz każdy sekwencyjnie:

1. Uruchom wszystkie wątki z main
2. W miarę kończenia każdego, zsynchronizuj go do feature/user-v2 używając “Apply”
3. Jeśli zmiany kolidują, użyj “Overwrite local”, żeby zresetować i czysto zaaplikować

To efektywnie zrównolegluje development feature’a na wielu agentach Codex.

Ograniczenia branchy

Git wymusza regułę jednego brancha na worktree. Jeśli utworzysz feature/a na worktree, nie możesz jednocześnie checkoutować feature/a w swoim lokalnym checkout ani żadnym innym worktree. Zobaczysz:

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

Rozwiązanie: użyj “Sync with local” zamiast ręcznego checkoutu brancha. Lub checkoutuj inny branch na worktree, żeby zwolnić nazwę.

Czyszczenie worktree

Każdy worktree kopiuje pliki repozytorium, zależności i cache build. To szybko się sumuje. Codex zarządza czyszczeniem automatycznie z tymi regułami:

Nigdy nie czyszczone:

• Worktree powiązane z przypiętymi konwersacjami
• Worktree promowane do sidebara

Kwalifikujące się do czyszczenia:

• Starsze niż 4 dni
• Gdy masz więcej niż 10 worktree

Przed usunięciem worktree Codex zapisuje snapshot. Jeśli otworzysz ponownie wątek, którego worktree został wyczyszczony, zobaczysz opcję przywrócenia.

Obserwuj miejsce na dysku

Jeśli uruchamiasz częste automatyzacje, każda tworzy nowy worktree. Archiwizuj uruchomienia automatyzacji, których już nie potrzebujesz, i unikaj przypinania uruchomień, chyba że zamierzasz długoterminowo zachować ich worktree. Monitoruj użycie dysku za pomocą du -sh ~/.codex/worktrees/ okresowo.

Gdy coś nie działa

• “Branch is already used by worktree”: Inny worktree ma ten branch checkoutowany. Przełącz ten worktree na inny branch lub użyj Sync with local zamiast tego.
• Konflikty synchronizacji: Gdy twój lokalny checkout znacząco się rozjechał z worktree, “Apply” może się nie powieść. Użyj “Overwrite local” dla czystego startu lub rozwiąż konflikty ręcznie w terminalu.
• Brakujące zależności w worktree: Worktree to świeży checkout. Skonfiguruj lokalny skrypt setup środowiska w ustawieniach aplikacji Codex, żeby automatycznie instalował zależności przy tworzeniu worktree.
• Pliki .gitignore nie przenoszą się: Proces synchronizacji używa operacji Git, więc wszystko w .gitignore (jak node_modules, .env, artefakty build) nie zostanie przeniesione. Uruchom skrypt setup po synchronizacji.

Co dalej

• Automatyzacje — Automatyzacje działają w dedykowanych worktree, więc zrozumienie worktree to fundament
• Mistrzostwo w aplikacji — Pełny workflow aplikacji Codex w tym zarządzanie wieloma projektami
• Operacje wsadowe — Łącz worktree z zadaniami chmurowym dla zmian na dużą skalę