Um Git worktree é um diretório de trabalho adicional vinculado a um repositório Git existente. Ele possui sua própria branch em checkout, seu próprio índice (index) e seus próprios arquivos não rastreados, mas compartilha a base de objetos, referências e configurações com o repositório principal. Para agentes de programação que operam em paralelo, essa é a unidade de isolamento perfeita: cada agente ganha uma pasta onde nenhum outro processo interfere, seus commits vão para uma branch exclusiva e a criação desse ambiente é um simples checkout, em vez de uma clonagem demorada ou subida de contêiner. Este artigo aborda os comandos essenciais, explica por que os worktrees superam diretórios compartilhados, detalha as armadilhas comuns e mostra como o Ivy Tendril provisiona e descarta um worktree por plano.
O que é um worktree
Por padrão, todo repositório Git dispõe de uma única pasta de trabalho. O comando git worktree add permite acoplar outras. Cada diretório resultante é um checkout completo no qual você pode navegar com cd, alterar arquivos, executar testes e commitar.
# Criar um worktree na pasta superior com uma nova branch
git worktree add ../feature-x -b feature-x
# Listar todos os worktrees vinculados ao repositório
git worktree list
# /Users/dev/app a1b2c3d [main]
# /Users/dev/feature-x a1b2c3d [feature-x]
A nova pasta gerada contém um arquivo .git (e não um subdiretório). Esse arquivo referencia diretamente .git/worktrees/feature-x no repositório raiz, onde residem o índice e o ponteiro HEAD daquele espaço. Objetos, referências, hooks do Git e configurações são lidos do repositório principal. Qualquer commit criado em ../feature-x fica imediatamente disponível na pasta principal via git log feature-x, sem necessidade de push ou fetch.
Essa arquitetura impõe duas regras indispensáveis: uma mesma branch só pode estar em checkout em um único worktree por vez, e a pasta do worktree deve ficar fora do diretório principal para não ser tratada como arquivos não rastreados.
Por que worktrees superam diretórios compartilhados
Um agente de código inspeciona e modifica arquivos, roda testes e comita. Dois agentes agindo simultaneamente no mesmo diretório produzem um diff misturado e confuso, e nenhum teste consegue isolar os efeitos de cada alteração. As alternativas viáveis seriam um clone por agente, um contêiner Docker por agente ou um worktree por agente.
| Abordagem | Árvore e branch exclusivas | Base de objetos compartilhada | Custo de inicialização | Isolamento de runtime |
|---|---|---|---|---|
| Diretório compartilhado | Não | Sim | Zero | Nenhum |
| Clone dedicado por agente | Sim | Não (cópia total de dados) | Clonagem completa + dependências | Nenhum |
| Contêiner por agente | Sim | Não (a menos que montado) | Download de imagem + boot | Sim |
| Worktree por agente | Sim | Sim | Checkout instantâneo | Nenhum |
O worktree fornece exatamente o que o agente necessita para garantir a integridade do código (uma árvore de arquivos e uma branch privadas), sem a lentidão ou complexidade de ambientes virtuais desnecessários. Como a base de objetos é compartilhada, repositórios corporativos com anos de histórico demandam apenas o checkout do estado atual. Caches de gerenciadores de pacotes (como pnpm, Cargo e NuGet) permanecem compartilhados no nível do usuário.
Contêineres continuam sendo necessários quando os agentes precisam instalar dependências de sistema ou subir portas locais de rede. Ambas as técnicas podem se somar: um worktree pode ser montado dentro de um contêiner. Para o ciclo comum de edição, testes, linter e commits, o worktree nativo é perfeito.
Veja também padrões de orquestração de agentes para compreender o papel do isolamento na engenharia autônoma.
Armadilhas comuns e como evitá-las
Worktrees eliminam conflitos entre diretórios, mas demandam boas práticas em três cenários recorrentes.
1. Dois agentes alterando os mesmos arquivos em branches distintas
Worktrees isolam pastas, não decisões arquiteturais. Se dois planos modificam auth/session.ts, ambas as branches comitarão perfeitamente de forma isolada, mas a segunda gerará conflito no merge. A solução é atuar no planejamento: identifique previamente as dependências entre arquivos e execute as tarefas em sequência ou reparta o escopo de modo que cada plano tenha um módulo sob sua responsabilidade.
2. Diretórios com alterações pendentes (Dirty Trees)
Se um agente for interrompido ou se uma rotina de teste gerar arquivos temporários, o worktree acumula arquivos não comitados. Por segurança, o git worktree remove não exclui pastas modificadas. O orquestrador deve comitar todo o material gerado pelo agente em sua própria branch para que nada seja perdido antes de desmantelar a pasta.
# Inspecionar arquivos pendentes
git -C ../feature-x status --short
# Remover um worktree limpo
git worktree remove ../feature-x
# Forçar remoção se as alterações forem descartáveis
git worktree remove --force ../feature-x
3. Worktrees órfãos acumulados
Worktrees criados manualmente tendem a ser esquecidos, retendo branches e ocupando disco. Se um diretório for deletado com rm -rf em vez de git worktree remove, o Git preserva referências inválidas em .git/worktrees/.
# Verificar itens passíveis de limpeza
git worktree prune --dry-run --verbose
# Limpar referências obsoletas
git worktree prune
A regra de ouro é simples: o mesmo software que provisiona o worktree deve se encarregar de destruí-lo no momento adequado do ciclo de vida da demanda.
Como o Ivy Tendril utiliza worktrees
O Ivy Tendril é um aplicativo desktop local-first (macOS, Windows, Linux) que gerencia agentes desde a concepção do plano até o pull request aprovado. Os worktrees representam sua unidade primária de execução. Confira a visão geral do produto e as fases do ciclo de vida.
- Um worktree por plano: Ao aprovar uma demanda, o Tendril provisiona automaticamente o worktree e sua branch exclusiva. Vários planos rodam ao mesmo tempo sem impactar a main.
- Verificação no worktree: Testes e cálculos de diff são processados dentro do ambiente isolado da tarefa. O painel de Review exibe diff e resultados lado a lado.
- Exclusão pós-merge: Quando a pull request é aceita no GitHub, o Tendril remove o worktree de forma limpa.
- Suporte multiagente: Execute Claude Code, OpenAI Codex CLI, GitHub Copilot CLI, Gemini CLI ou OpenCode de acordo com a necessidade de cada tarefa.
- 100% Local: Código, planos, memória técnica e logs ficam salvos na sua máquina. Consulte desenvolvimento local com IA.
Comece a construir com Ivy Tendril
Adote o paralelismo com total isolamento em sua rotina de desenvolvimento:
- Explore o código: Veja o repositório do Ivy Tendril no GitHub (open source).
- Documentação completa: Acesse nossos manuais técnicos em tendril.ivy.app.
- Fale com a engenharia: Envie um e-mail para renco@ivy.app e agende uma conversa técnica de 30 minutos.