Git worktrees para agentes de IA: comandos, armadilhas e automação

O que é um git worktree?

Um git worktree é um diretório de trabalho ligado a um repositório existente, com a sua própria branch em checkout. O clone normal é o worktree principal; cada git worktree add cria um worktree vinculado em outra pasta. Todos compartilham o mesmo armazenamento de objetos do .git, então commits, branches e remotes são os mesmos em todo lugar, mas cada pasta tem seus arquivos, seu index e seu HEAD.

Comparado a um segundo git clone, o worktree é mais rápido de criar, ocupa menos disco porque o histórico é compartilhado, e um commit feito num worktree aparece na hora nos outros. Comparado a trocar de branch, nada vai para o stash e nada é interrompido.

Por que agentes de IA precisam de git worktrees?

Agentes de IA precisam de worktrees porque editam arquivos direto e rodam por minutos seguidos. Dois agentes na mesma pasta sobrescrevem as edições um do outro, dividem a mesma staging area e brigam pelo build. Um worktree por agente dá a cada um uma cópia isolada numa branch própria, e é isso que torna seguro rodar agentes em paralelo e revisar cada resultado como um diff limpo na revisão de diff.

Como configurar git worktrees para agentes de IA, passo a passo?

1. 1

   Confira a versão do git

   Rode git --version. O git worktree faz parte do git desde a versão 2.5, então qualquer instalação atual serve.

2. 2

   Atualize a branch base

   No checkout principal, rode git fetch origin para os worktrees novos partirem do origin/main mais recente.

3. 3

   Crie um worktree por agente

   Rode git worktree add ../myapp-auth -b feat/auth origin/main. Isso cria a pasta ../myapp-auth com uma branch nova feat/auth a partir do origin/main. Repita com pasta e branch novas para cada agente.

4. 4

   Traga os arquivos ignorados pelo git

   Um worktree novo é um checkout limpo: node_modules, .env e caches de build não vêm junto. Instale as dependências e copie os arquivos locais que cada agente precisa.

5. 5

   Inicie o agente dentro do worktree

   cd ../myapp-auth e inicie o agente ali, por exemplo claude ou codex. O diretório de trabalho do agente é o worktree, então as edições ficam nele.

6. 6

   Revise e faça o merge da branch

   Revise com git diff origin/main...feat/auth, rode os testes e depois faça push da branch e abra um pull request, ou faça o merge local.

7. 7

   Remova o worktree no fim

   Rode git worktree remove ../myapp-auth e depois git branch -d feat/auth se a branch já entrou. Rode git worktree prune se algum dia você apagou a pasta de um worktree na mão.

Quais comandos de git worktree eu realmente preciso?

Quatro comandos resolvem quase tudo: add, list, remove e prune. O resto é para casos específicos.

git fetch origin
git worktree add ../myapp-auth -b feat/auth origin/main
git worktree add ../myapp-tests -b test/checkout origin/main
git worktree list
# ...os agentes trabalham, você revisa e faz o merge...
git worktree remove ../myapp-auth
git branch -d feat/auth

Quais são as armadilhas mais comuns com git worktree?

• Uma branch só vive em um worktree. fatal: 'main' is already checked out significa que outro worktree está com ela. Crie uma branch nova por worktree.
• Faltam os arquivos ignorados pelo git. .env, node_modules e caches não vêm junto. Reserve tempo para configurar ou automatize a cópia.
• Portas e serviços compartilhados colidem. Dois servidores de desenvolvimento na porta 3000 falham. Dê a cada worktree sua porta e, se precisar, seu banco de testes.
• Worktrees dentro do repositório confundem as ferramentas. Um worktree aninhado na pasta principal aparece em buscas e watchers. Mantenha os worktrees numa pasta irmã ou num diretório ignorado pelo git.
• Apagar a pasta na mão deixa metadados. O git ainda acha que a branch está em checkout. Rode git worktree prune.
• `--force` perde trabalho. git worktree remove --force descarta mudanças não commitadas. Faça commit ou confira o diff antes.
• O disco enche. O histórico é compartilhado, mas cada worktree tem seus arquivos e dependências.

Deixe os worktrees com o Tallos. Cada workspace é um, criado e limpo para você.

Baixar o Tallos →

Como o Tallos automatiza os git worktrees?

O Tallos é nativo em worktrees: toda tarefa que você começa vira um workspace, e todo workspace é um git worktree de verdade, com branch, arquivos e sessões de agente próprios. Você nunca digita git worktree add, mas sempre pode abrir um terminal e usar git puro dentro de qualquer workspace.

• Criação em segundo plano. O Tallos roda git fetch e git worktree add em segundo plano e mostra o progresso na aba nova; você segue trabalhando.
• Escolha do ponto de partida. Parta da branch base, de outra branch local (para empilhar sobre um PR em revisão), de um commit específico ou de uma branch remota que o Tallos busca para você.
• Nome da branch. Vem do nome do workspace ou do item vinculado do GitHub, Linear, Jira ou GitLab. Defina o seu em Avançado → Nome da branch.
• Arquivos ignorados pelo git. Liste os arquivos a copiar no .worktreeinclude na raiz do repositório e configure caminhos compartilhados por repositório em Configurações → Repositório.
• Limpeza. Excluir um workspace remove a pasta e a branch depois da confirmação. Se o git mantiver uma branch por ela ter commits sem merge, o Tallos deixa você revisar.
• Seus próprios worktrees. Worktrees criados com git worktree add fora do Tallos podem aparecer na barra lateral, e um worktree removido pela CLI some do Tallos na próxima atualização.

Veja na prática em como rodar várias sessões do Claude Code ou leia a página de workspaces paralelos. Termos novos? O glossário define worktree, workspace e base ref.