O que é um git worktree e por que quem faz vibe coding usa?

O que o comando faz

Um repositório git normalmente tem uma pasta de trabalho: a que você clonou. O comando git worktree add cria outra pasta ligada ao mesmo histórico, com a própria branch, e a partir daí as duas convivem: git worktree list mostra todas, e git worktree remove apaga uma quando o trabalho acabou. O histórico é um só; o que se multiplica é o lugar onde se edita.

A pasta nova nasce sem dependências e sem os arquivos de ambiente, que não são versionados. O ritual da casa copia os dois antes de começar: as dependências por clone do sistema de arquivos, que leva segundos, e o arquivo de env por cópia. Link simbólico pra pasta de dependências não serve, porque o bundler recusa um caminho que aponta pra fora do projeto.

Por que isso importa com agentes

O git é de um escritor só. Quando duas sessões de agente trabalham no mesmo checkout, uma troca a branch embaixo da outra, a segunda commita em cima, e o trabalho das duas vira um diff misto que ninguém consegue separar depois. Dos tropeços de começo de tarefa, é o único que piora conforme se usa mais IA, não menos.

A prática nasceu de um caso real num projeto irmão deste site: duas sessões editando a mesma página, uma rebaseando por cima da outra. Desde então toda sessão começa num worktree próprio, criado a partir do que está no remoto, mesmo em repositório de uma pessoa só. Repositório solo não quer dizer sessão solo.

O fluxo que a gente usa

Começa com um fetch do remoto e o worktree novo a partir dele, senão a pasta nasce atrasada. Em seguida, dependências e env copiados, e a sessão trabalha, roda o gate e commita ali dentro. Na hora de subir, um rebase pra pegar o que outras sessões já subiram, o push da branch do worktree direto pro master remoto e a remoção do worktree. O checkout original não é tocado em momento nenhum, e guardar mudança com git stash é proibido: checkout sujo vira worktree novo.

Quando isso importa

• Você abriu uma segunda sessão do agente no mesmo projeto e a primeira apareceu numa branch que você não escolheu.
• Você quer rodar duas ou três tarefas em paralelo no mesmo repositório sem esperar uma terminar pra começar a outra.
• Você está montando o ritual de início de tarefa do time e precisa decidir onde cada sessão trabalha.

Nossa posição

Aqui worktree é o normal, não a exceção: toda sessão começa num, mesmo em repositório de uma pessoa só, porque repositório solo não significa sessão solo. E git stash é proibido: checkout sujo vira worktree novo, não pilha de mudança guardada que alguém esquece.