Git worktree: trabalho paralelo sem enlouquecer (e por que os agentes de IA os adoram)

Uma única cópia do repositório, muitos diretórios de trabalho independentes: o recurso do Git que mudou a forma como eu troco de contexto.

Há um momento no dia de qualquer desenvolvedor que você conhece de cor. Você está imerso em uma feature complicada: doze arquivos modificados, a IDE que finalmente reindexou tudo, o depurador parado em um breakpoint, a cabeça segurando um castelo mental fragílimo. E nesse exato instante chega a mensagem: “Tem um bug crítico em produção, precisamos de um fix agora.”

O que você faz? As opções clássicas são três, e as três doem. Você pode dar git stash e rezar para lembrar do que tinha em mãos. Você pode commitar um trabalho pela metade com uma mensagem do tipo WIP ainda não funciona que vai sujar o histórico para sempre. Ou pode clonar de novo o repositório em outra pasta, esperar o download, reconfigurar o ambiente e reconstruir tudo do zero. De qualquer jeito, aquele castelo mental desaba.

Existe uma quarta opção, e desde que a descobri eu a uso quase todos os dias: os git worktree. E aqui chego ao verdadeiro motivo pelo qual escrevi este post: os worktree estão no Git há anos, e mesmo assim continuo vendo um monte de desenvolvedores, até excelentes, que não os usam e nem sabem que existem. Toda vez que mostro para alguém a reação é a mesma: “como é que eu trabalhei sem isso até hoje?”. Então vamos deixar as coisas claras de uma vez por todas: de onde vêm, qual problema realmente resolvem, como se usam e por que, hoje, viraram uma ferramenta fundamental também para os agentes de codificação baseados em IA.

De onde eles vêm

O comando git worktree chegou com o Git 2.5, lançado em 27 de julho de 2015. Antes disso, a regra implícita era de ferro: um repositório, um diretório de trabalho. Se você quisesse trabalhar em dois branches ao mesmo tempo em duas pastas distintas, o único caminho oficial era um git clone repetido, com todo o desperdício que isso acarreta: espaço em disco duplicado, objetos baixados de novo, remotes para reconfigurar e nenhum vínculo entre as cópias.

Os worktree romperam essa restrição. A ideia de fundo é elegante: o histórico de um repositório (commits, branches, tags, objetos) vive uma única vez dentro de .git, enquanto os diretórios de trabalho que o materializam em disco podem ser muitos. Uma única fonte de verdade, muitas mesas de trabalho voltadas para ela.

Um único tronco (o histórico compartilhado em .git) do qual se ramifica uma copa de diretórios de trabalho independentes. É exatamente assim que os git worktree funcionam.

O problema que eles realmente resolvem

O modelo clássico do Git tem um gargalo preciso: o diretório de trabalho é um só, então ele só pode estar em um branch por vez. git checkout (ou o mais moderno git switch) é uma operação destrutiva sobre o seu workspace: reescreve os arquivos em disco para refletir o branch de destino. Daí vêm todos os incômodos que você conhece.

• As mudanças não commitadas atrapalham. Se você tem arquivos sujos, o Git se recusa a trocar de branch, ou te obriga a dar stash. O stash é uma pilha escondida na qual é facílimo esquecer as coisas.
• Trocar de branch invalida o trabalho de build. Você troca de branch e os timestamps dos arquivos mudam: a IDE reindexa, o compilador reconstrói metade da solução, o cache de testes é esvaziado. Em um projeto Delphi de certo tamanho, ou em qualquer codebase grande, isso significa minutos perdidos a cada salto.
• Você não consegue olhar dois branches no mesmo momento. Quer comparar o comportamento da feature com o de main lado a lado? Com um único diretório de trabalho você não consegue: tem que pular para frente e para trás, reconstruindo toda vez.

Os worktree eliminam o gargalo na raiz. Cada contexto de trabalho ganha sua pasta, com seus arquivos, seu estado de build, independente dos demais. Trocar de contexto vira um cd, não um git stash seguido de uma reconstrução.

Como usar: os quatro comandos de que você precisa

Toda a API dos worktree cabe em um punhado de comandos. Vamos partir do princípio de que você está dentro de um repositório já clonado.

Criar um worktree em um branch existente, em uma pasta ao lado da do projeto:

# Cria ../app-hotfix como diretório de trabalho posicionado no branch hotfix/login
git worktree add ../app-hotfix hotfix/login

Criar um worktree e um novo branch juntos, de uma vez só:

# Cria o branch feature/export partindo de main e dá a ele a própria pasta
git worktree add -b feature/export ../app-export main

Listar todos os worktree ativos, com o caminho e o branch em que estão:

git worktree list
# /home/daniele/app           a1b2c3d [main]
# /home/daniele/app-hotfix    e4f5g6h [hotfix/login]
# /home/daniele/app-export    i7j8k9l [feature/export]

Remover um worktree quando você terminar, e limpar as referências órfãs que sobrarem:

git worktree remove ../app-hotfix
git worktree prune   # limpa os metadados de worktree apagados na mão

Uma observação que convém ter em mente desde já: o Git não deixa você fazer checkout do mesmo branch em dois worktree ao mesmo tempo. É uma proteção deliberada, não um limite arbitrário. Duas pastas modificando o mesmo branch seriam a receita perfeita para se confundir e pisar nos commits um do outro. Se você realmente precisar, existe o --force, mas em 99% dos casos aquela mensagem de erro está te salvando de uma encrenca.

Há também alguns comandos a mais que você usa com menos frequência, mas é bom saber que existem: git worktree move para mover um diretório de trabalho para outro caminho, git worktree lock / unlock para impedir que um worktree (por exemplo em um disco removível ou um compartilhamento de rede) seja limpo automaticamente, e git worktree repair para reparar as referências quando você moveu pastas na mão e o Git se perdeu. Para o uso diário, no entanto, os quatro comandos acima cobrem tudo.

E se você prefere o mouse ao teclado, não fica de fora: as ferramentas gráficas mais maduras expõem os worktree com a mesma naturalidade. No Git Extensions, por exemplo, há um submenu inteiro dedicado em Repository, Worktrees, com as opções para criar um novo e para gerenciar os existentes.

Criar e gerenciar worktree pelo Git Extensions: sem linha de comando, só um menu.

Um layout que se mantém arrumado sozinho

Se os worktree viram parte estável do seu fluxo, um pequeno truque de organização os deixa ainda mais limpos. Em vez de espalhar pastas a esmo pelo disco, uma convenção muito difundida é clonar o repositório como bare dentro de uma pasta .bare, e manter todos os worktree como subpastas ao lado dela, uma por branch:

git clone --bare git@github.com:usuario/app.git app/.bare
cd app
echo "gitdir: ./.bare" > .git
# checkout dos branches existentes, cada um na sua pasta
git worktree add main main
git worktree add feature-export feature/export

Assim o seu projeto vira uma pasta app/ que contém main/, feature-export/ e por aí vai, cada uma pronta para usar, com o histórico compartilhado escondido em .bare. Repare que eu sempre passo o branch como segundo argumento: se você omitir, o Git usa só o último segmento do caminho como nome do branch (de feature/export ele pegaria export) e muitas vezes acaba criando um branch novinho, raramente o que você queria. Não é um setup obrigatório, mas quando você trabalha com muitos worktree, você se agradece depois.

Exemplos da vida real

A teoria é curta, a utilidade é enorme. Estes são os cenários em que eu abro um worktree sem nem pensar.

O hotfix enquanto uma feature está pela metade

De volta à cena do início. Você está no meio de feature/novo-relatorio, diretório de trabalho cheio de mudanças. A emergência chega. Em vez de dar stash:

git worktree add -b hotfix/crash-pdf ../app-hotfix main
cd ../app-hotfix
# aqui você corrige o bug, commita, faz push, abre o PR
# enquanto isso a sua feature continua intacta na outra pasta

Apagado o incêndio, você dá cd de volta para a pasta da feature e encontra tudo exatamente como deixou: arquivos abertos, estado de build, breakpoints. Zero stash, zero reconstruções.

O code review sem atrapalhar o próprio trabalho

Um colega te pede para revisar o PR dele. Você quer rodar de verdade, não só ler o diff em uma página web. Com um único diretório de trabalho você teria que interromper o seu trabalho. Com um worktree, não:

git worktree add ../app-review feature/colega-pr
cd ../app-review
# você compila, roda, experimenta a feature do colega
# o seu branch pessoal nem é tocado

Uma build longa em paralelo

O caso clássico dos projetos grandes: a build completa ou a suíte de testes leva minutos. Em vez de ficar de braços cruzados, você dispara a build pesada em um worktree e continua escrevendo código em outro. Duas pastas, dois estados de build independentes, nenhuma interferência.

A comparação lado a lado de duas versões

Precisa entender por que um comportamento mudou entre main e o branch de release? Abra dois worktree, um para cada, e coloque-os literalmente um ao lado do outro em duas janelas do editor. Nada de pular para frente e para trás: você olha os dois no mesmo instante.

Por que os agentes de IA os usam tanto

Aqui os worktree passam de comodidade pessoal a habilitadores de toda uma forma de trabalhar. Os agentes de codificação baseados em IA, como o Claude Code e similares, têm um apetite natural por trabalho paralelo: rodar várias tarefas ao mesmo tempo, cada uma modificando arquivos, disparando builds e commitando por conta própria.

O problema é que várias instâncias trabalhando no mesmo diretório de trabalho pisariam umas nas outras: um agente muda um arquivo enquanto outro o está compilando, os branches se sobrescrevem, o estado fica inconsistente. A solução que essas ferramentas adotam é justamente o git worktree: a cada agente, ou a cada tarefa paralela, se atribui um worktree isolado. Cada um tem a sua pasta, o seu branch, o seu estado de build, mas todos compartilham o mesmo banco de dados de objetos, então não há duplicação do histórico, e os resultados se reintegram no repositório principal com um merge normal.

É exatamente o mesmo padrão que eu uso na mão para o hotfix, levado a escala industrial e automatizado. Um agente trabalha na feature A em ../app-feature-a, outro na feature B em ../app-feature-b, um terceiro está rodando os testes em ../app-tests, e nenhum dos três sequer sabe da existência dos outros. O isolamento que torna os worktree cômodos para nós é a mesma propriedade que os torna indispensáveis para orquestrar vários agentes em paralelo.

Alguns cuidados

Os worktree são sólidos, mas vale a pena saber de algumas coisas antes de se queimar.

• Mesmo branch, um único worktree. Já dissemos: é uma proteção, não um defeito. Para testar o mesmo branch em dois lugares, crie um branch auxiliar.
• A configuração é compartilhada, o diretório de trabalho não. Os worktree compartilham config, os objetos e os branches, mas cada um tem o seu próprio HEAD, o seu próprio index e os seus próprios arquivos. O stash, atenção, é compartilhado no nível do repositório: não o imagine preso a um worktree específico.
• Faça a limpeza. Quando você apaga uma pasta de worktree na mão em vez de usar git worktree remove, sobram metadados órfãos: git worktree prune os limpa. git worktree list é o seu painel para não perder a conta.
• Os submódulos exigem atenção. Se o projeto usa submódulos, lembre-se de inicializá-los também no novo worktree; eles não se materializam sozinhos.

Pontos-chave

• Um repositório, muitos diretórios de trabalho. Os git worktree, introduzidos no Git 2.5 (julho de 2015), te dão várias pastas de trabalho a partir do mesmo .git, cada uma em um branch diferente.
• Trocar de contexto vira um cd. Acabou o git stash e o reclonar para atender um hotfix urgente: você abre um worktree, trabalha, fecha, e o trabalho original continua intacto.
• O estado de build sobrevive. Cada worktree mantém a sua própria indexação e cache de compilação: trocar de contexto não obriga a IDE a recomeçar do zero.
• Poucos comandos. git worktree add, git worktree list, git worktree remove, git worktree prune: é praticamente só isso.
• São o motor do trabalho paralelo dos agentes de IA. Atribuir um worktree isolado a cada agente ou tarefa é o padrão que permite a vários agentes trabalhar no mesmo repositório sem colidir.
• Uma proteção para lembrar. O mesmo branch não pode estar em dois worktree ao mesmo tempo: é proposital, e é bom assim.

Perguntas frequentes

Em qual versão do Git os worktree chegaram?

O comando git worktree foi introduzido no Git 2.5, lançado em 27 de julho de 2015. Desde então é um recurso estável e está disponível em qualquer instalação moderna do Git.

Qual a diferença entre git worktree e clonar o repositório de novo?

Um clone novo cria uma cópia completamente separada: banco de dados de objetos duplicado, o dobro de espaço em disco, remotes para reconfigurar e nenhum vínculo com o original. Um worktree, por outro lado, só adiciona um diretório de trabalho: o histórico, os branches e os objetos ficam compartilhados em um único .git. É muito mais leve, e os branches criados em um worktree ficam imediatamente visíveis para os outros.

Posso fazer checkout do mesmo branch em dois worktree?

Não, e de propósito. O Git impede posicionar o mesmo branch em dois worktree ao mesmo tempo para evitar que duas pastas reescrevam o estado dele de forma inconsistente. Se você realmente precisar, pode forçar com --force, mas quase sempre a solução correta é criar um branch auxiliar.

Por que os agentes de codificação com IA usam worktree?

Porque eles habilitam o trabalho paralelo sem conflitos. Ao atribuir a cada agente ou tarefa um worktree isolado, vários agentes podem modificar arquivos, compilar e commitar ao mesmo tempo no mesmo repositório sem pisar uns nos outros, compartilhando ainda assim um único histórico no qual os resultados se reintegram.

Como removo um worktree quando termino?

Use git worktree remove <caminho> para apagá-lo de forma limpa. Se, em vez disso, você apagou a pasta na mão, rode git worktree prune para limpar os metadados órfãos. Com git worktree list você confere a qualquer momento quais worktree estão ativos.