Entenda o risco de mexer no original
O Rui tem um site simples da loja, na pasta loja-rui/site. Os clientes já usam. Um dia ele pediu ao Codex: "refaça o visual inteiro do site, com cores novas e um menu diferente".
O Codex mexeu direto nos arquivos originais. O visual novo ficou estranho, e o Rui não sabia mais como era o antigo. Esse é o risco: teste feito no original é teste sem volta, a não ser que exista uma cópia.
🆕 Novo aqui? Cinco palavras deste módulo
- Git — um programa que guarda o histórico de versões de uma pasta. Cada versão salva vira um ponto ao qual você pode voltar.
- Worktree — uma cópia de trabalho paralela do projeto, criada pelo Git, para mexer sem tocar no original.
- Branch — uma linha paralela de mudanças. Pense num desvio da estrada que pode voltar à pista principal.
- main — o nome da linha principal (em projetos mais antigos, master). É o "original".
- Merge — juntar as mudanças de uma linha paralela de volta na principal.
Como ler o desenho: em cima, a seta do Codex atinge o original e a rachadura fica para sempre. Embaixo, a seta passa por cima do original e cai na cópia tracejada. O original nem fica sabendo do teste.
✗ Testar no original
- ✗ O site que os clientes usam muda na hora
- ✗ Difícil lembrar como era antes
- ✗ Duas ideias ao mesmo tempo se misturam
✓ Testar numa cópia
- ✓ O original segue funcionando
- ✓ Comparar antes e depois lado a lado
- ✓ Descartar sem prejuízo se não gostar
Veja o que é uma worktree
Copiar a pasta na mão ("site-copia", "site-copia2") até funciona, mas vira bagunça rápido. A worktree é a forma organizada de fazer isso: o Git cria uma segunda pasta de trabalho ligada ao mesmo histórico do projeto.
As duas pastas sabem uma da outra. Por isso, depois, dá para levar só as mudanças boas da cópia para o original, sem arrastar arquivo por arquivo. Para isso funcionar, a pasta do projeto precisa estar sob controle do Git.
Como ler o desenho: as duas pastas embaixo parecem iguais, mas o index.html de cada uma está diferente. O bloco de cima é o que as une: o mesmo histórico. É ele que permite juntar depois.
no seu computador
ligada ao original
ideia arriscada
sem dó
💡 Worktree também é local
A cópia fica no seu computador, como o original. Não é nuvem nem backup externo. Se o disco quebrar, as duas vão junto: backup continua sendo outro assunto.
Conheça branch e main sem medo
Toda worktree trabalha numa branch: uma linha paralela de mudanças. A linha principal se chama main. Quando o app mostra "main" e outros nomes, ele está dizendo em que linha cada pasta está.
Pense no metrô. A main é a linha azul que todo mundo usa. A branch é um ramal que sai dela para testar uma estação nova. Se a estação der certo, o ramal se reconecta à linha azul. Se não der, o ramal é desativado e a linha azul nem percebe.
Como ler o desenho: a linha grossa azul é a main, sempre em uso. O ramal ciano de cima saiu em v2, testou duas vezes e voltou em v4: isso é o merge. O ramal cinza de baixo não deu certo e terminou no X, sem estragar a linha principal.
| Você vê | Quer dizer | Precisa se preocupar? |
|---|---|---|
| main (ou master) | A linha principal, o original | Não. É onde você normalmente está |
| Outro nome de branch | Uma linha paralela de teste | Só se você não pediu: pergunte ao Codex |
| Várias worktrees listadas | Cópias de trabalho em paralelo | Não. O Codex às vezes cria sozinho |
O que olhar na tabela: a coluna da direita. Na maior parte dos casos a resposta é "não": esses nomes só informam onde cada cópia está.
Crie uma worktree no Codex
Você não precisa saber Git para usar worktree no Codex. No aplicativo, ao começar uma conversa, existe a opção de trabalhar numa nova worktree local. No terminal, basta abrir com codex --worktree.
O Rui voltou ao visual novo do site, agora do jeito certo. O nome do botão pode mudar entre versões; procure perto da caixa de mensagem algo como "worktree" ou "trabalhar em paralelo".
Confira se a pasta usa Git
Pergunte ao Codex: "esta pasta está sob controle do Git?". Se não estiver, peça para ele ativar e salvar uma primeira versão antes de qualquer teste.
Comece a conversa numa worktree
No app, escolha a opção de nova worktree local antes de mandar a mensagem. No terminal, entre na pasta e rode codex --worktree.
Peça o teste arriscado
"Refaça o visual do site com cores novas e menu diferente." Tudo acontece na cópia.
Compare antes de decidir
Abra a prévia da cópia e a do original lado a lado. Só então decida: juntar (próximo tópico) ou descartar.
Como ler o desenho: na barra lateral, o projeto do Rui agora mostra duas linhas, main e visual-novo (destacada, porque é onde a conversa está). O seletor brilhante embaixo é onde se escolhe a worktree antes de mandar a mensagem. Os nomes da tela são ilustrativos.
Objetivo: começar uma sessão numa cópia de trabalho nova, sem tocar no original.
cd <caminho-da-pasta-loja-rui> codex --worktree
Junte o resultado de volta
O visual novo ficou bom. Agora as mudanças precisam sair da cópia e entrar no original. Esse passo se chama merge. Você não precisa fazer à mão: peça ao Codex.
O cuidado é um só: peça para ele mostrar o que vai mudar antes de juntar. Se o original também mudou enquanto você testava, os dois lados podem ter mexido no mesmo trecho. Isso se chama conflito, e o Codex explica e resolve com você.
Como ler o desenho: leia da esquerda para a direita. O quadro do meio é o momento mais importante: é ali que você vê o que vai entrar no original e aprova. A seta tracejada de baixo é a saída de emergência: descartar sem juntar nada.
Objetivo: levar as mudanças da worktree para o original só depois de ver o que muda.
Gostei do resultado desta worktree. Antes de juntar com a main, me mostre em linguagem simples quais arquivos mudam e o que muda em cada um. Se houver conflito com a main, explique e me pergunte como resolver. Só junte depois que eu disser "pode juntar".
💡 Descartar também é resultado
Se o teste não ficou bom, diga "descarte esta worktree e volte para a main". Você aprendeu o que não quer sem ter estragado nada. Esse é o ponto da cópia.
Saiba quando você não precisa disso
Worktree nasceu para software feito em equipe: várias pessoas, ou vários agentes, mexendo no mesmo código ao mesmo tempo. Para o trabalho de escritório da Paula, quase nunca é preciso.
Se ela quer testar outro tom numa proposta, basta pedir "crie uma versão nova em outro arquivo e não mexa na original". E se aparecer uma worktree que você não pediu, não se assuste: o Codex às vezes cria sozinho para trabalhar em paralelo.
Como ler o desenho: quanto mais para a direita (mais risco) e para cima (mais gente mexendo), mais a worktree ajuda. A Paula vive no canto de baixo à esquerda, onde ela não faz diferença.
✓ Use worktree quando
- ✓ A mudança é grande e pode quebrar algo que está em uso
- ✓ Quer comparar duas ideias lado a lado
- ✓ Vários agentes vão mexer no mesmo projeto ao mesmo tempo
✗ Não precisa quando
- ✗ É um texto, um e-mail ou um post
- ✗ "Salvar como versão nova" já resolve
- ✗ A pasta nem usa Git e você não quer começar agora
Teste rápido (opcional): para que serve uma worktree?
🎓 Resumo do módulo
codex --worktree — e o Codex junta com revisão.Próximo módulo:
2.3 — A pasta .codex: configurações