git worktree: como trabalhar em várias branches ao mesmo tempo

O que o git worktree faz

O git worktree liga vários diretórios de trabalho a um mesmo repositório. Na pasta principal você tem aberta a branch da feature e, na pasta ao lado, a main para um hotfix urgente — e as duas existem ao mesmo tempo. Objetos, commits e branches são compartilhados: um commit feito em uma pasta aparece na hora na outra, sem push nem fetch.

Sem worktree, trocar de contexto fica assim: git stash, git switch main, correção, git switch de volta, git stash pop. Se o projeto tem um build demorado ou um node_modules pesado, cada troca de branch ainda invalida os caches. A segunda opção é clonar o repositório de novo, mas aí você tem duas cópias independentes do histórico, que precisam ser sincronizadas pelo servidor remoto.

O worktree junta o melhor das duas abordagens: pastas separadas, mas uma única base .git. Isso é possível porque uma branch no Git é só um ponteiro para um commit, não uma cópia dos arquivos, e nada impede que diferentes cópias de trabalho olhem para ponteiros diferentes.

Como criar uma cópia de trabalho adicional

A forma básica do comando é: git worktree add <caminho> [<branch>]. Vejamos as principais variações.

Abrir uma branch existente

cd ~/projects/shop
git worktree add ../shop-main main
Preparing worktree (checking out 'main')
HEAD is now at 3f2c1ab Atualizar README

Ao lado do projeto aparece a pasta shop-main com a branch main. Entre nela com um cd comum e trabalhe como em qualquer repositório.

Criar uma nova branch junto com a cópia de trabalho

git worktree add -b hotfix/payment-timeout ../shop-hotfix main

A flag -b cria a branch hotfix/payment-timeout a partir da main e a abre na nova pasta. A flag -B faz o mesmo, mas, se a branch já existir, a reseta para o commit indicado — use com cuidado.

Forma curta

git worktree add ../experiment

Se a branch não for informada, o Git cria uma nova branch com o nome do último componente do caminho (aqui, experiment) a partir do HEAD atual. Se já existir uma branch com esse nome, é ela que será aberta.

Cópia de trabalho sem branch

git worktree add --detach ../shop-v1.4 v1.4.0

O modo detached HEAD é prático para compilar ou testar um release antigo pela tag, sem criar branches desnecessárias.

Branch do servidor remoto

git fetch origin
git worktree add ../review-auth feature/auth

Se não existir a branch local feature/auth, mas houver exatamente uma remota origin/feature/auth, o Git cria uma branch local com rastreamento — como no git switch feature/auth. Assim é fácil revisar o pull request de outra pessoa sem mexer no seu trabalho.

Como listar e remover cópias de trabalho

git worktree list
/home/anna/projects/shop            a1b2c3d [feature/cart]
/home/anna/projects/shop-hotfix     7e8f9a0 [hotfix/payment-timeout]
/home/anna/projects/shop-v1.4       5d6e7f8 (detached HEAD)

A primeira linha é a cópia de trabalho principal (main worktree); as demais são as vinculadas (linked). Para scripts há a saída legível por máquina git worktree list --porcelain.

Quando o hotfix for integrado, remova a cópia de trabalho:

git worktree remove ../shop-hotfix
git branch -d hotfix/payment-timeout

O git worktree remove apaga a pasta e os registros internos. Se a cópia tiver alterações não commitadas ou arquivos não rastreados, o comando se recusa a rodar; adicione --force só se tiver certeza de que não precisa deles. Repare: a branch em si não é apagada, isso é feito à parte.

Se a pasta foi apagada manualmente

Apagar a pasta pelo gerenciador de arquivos ou com rm -rf deixa em .git/worktrees um registro "órfão", e a branch continua sendo considerada ocupada. Limpe esses registros:

git worktree prune --verbose

O Git faz isso sozinho periodicamente na coleta de lixo, mas não é preciso esperar.

Como funciona por dentro

Em uma cópia de trabalho vinculada, em vez da pasta .git há um arquivo .git com uma única linha:

gitdir: /home/anna/projects/shop/.git/worktrees/shop-hotfix

Nessa pasta interna ficam os dados exclusivos da cópia de trabalho: seu próprio HEAD, seu índice (staging area), seus estados de merge e rebase. Todo o resto é compartilhado: objetos, branches, tags, repositórios remotos, configuração e hooks.

Da tabela sai um detalhe nada óbvio: git stash list mostra as mesmas entradas em qualquer cópia. Isso é até prático — dá para guardar alterações em uma pasta e recuperá-las em outra.

A principal limitação: uma branch, uma cópia de trabalho

Não dá para abrir a mesma branch em duas cópias de trabalho. Se você tentar, o Git responde com um erro mais ou menos assim:

git worktree add ../shop-copy feature/cart
fatal: 'feature/cart' is already used by worktree at '/home/anna/projects/shop'

(em versões antigas do Git, o texto é "is already checked out at"). A limitação evita que um commit em uma pasta altere silenciosamente a branch debaixo dos pés da outra. Soluções: criar uma nova branch a partir do mesmo commit (-b), abrir a cópia em modo --detach ou, se for realmente necessário, usar --force, entendendo as consequências.

Pelo mesmo motivo, na pasta principal não dá para rodar git switch main enquanto a main estiver aberta em outra cópia de trabalho.

Cenários práticos

Hotfix urgente no meio de uma feature

git worktree add -b hotfix/null-price ../shop-hotfix main
cd ../shop-hotfix
# corrigimos, testamos
git commit -am "Corrigir falha com preço vazio"
git push -u origin hotfix/null-price
cd ../shop
git worktree remove ../shop-hotfix

A feature inacabada ficou como estava, nada precisou ir para o stash, e a IDE com o projeto aberto nem percebeu a troca.

Review de pull request rodando o código

Uma cópia separada para review permite compilar e rodar a branch de outra pessoa, executar os testes e continuar o seu trabalho na janela ao lado do editor.

Comparar o comportamento de duas versões

Duas cópias com tags diferentes podem rodar em paralelo em portas diferentes para comparar, por exemplo, o tempo de resposta da API antes e depois de uma otimização.

Testes e builds demorados

Rode a suíte completa de testes em uma cópia e continue escrevendo código na outra — o build não quebra porque você está mexendo nos arquivos.

Vários agentes de IA trabalhando em paralelo

Se vários agentes ou processos trabalham em tarefas, é prático dar a cada um sua própria cópia de trabalho em sua própria branch: eles não atrapalham uns aos outros, e os resultados vão direto para o repositório compartilhado.

Como organizar as pastas ao usar worktree sempre

Se você precisa de cópias de trabalho todo dia, defina uma estrutura, senão os diretórios vizinhos viram bagunça rapidinho. Um esquema popular é uma pasta-mãe do projeto com um repositório bare dentro e uma pasta por branch:

git clone --bare git@example.com:team/shop.git ~/projects/shop/.bare
cd ~/projects/shop
echo "gitdir: ./.bare" > .git
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin

git worktree add main
git worktree add -b feature/cart feature-cart main

A linha com remote.origin.fetch é necessária porque um clone bare, por padrão, não configura o rastreamento das branches remotas. No final, em ~/projects/shop ficam as pastas main e feature-cart, cada uma com sua branch, e nenhuma é "mais principal" que a outra.

Outro bom hábito é dar à pasta o mesmo nome da branch (trocando a barra por hífen). Assim, pela saída do git worktree list e pelo caminho no terminal, sempre fica claro onde você está. E, por fim, remova a cópia logo depois do merge da branch: cópias antigas ocupam espaço e mantêm branches "ocupadas".

Erros comuns e armadilhas

• Dependências e build não são compartilhados. Cada cópia é uma pasta separada, então node_modules, o ambiente virtual do Python, o .env e os artefatos de build terão de ser criados de novo. Arquivos não rastreados não vão para a nova cópia.
• Cópia de trabalho dentro da pasta principal. O comando git worktree add ./hotfix cria a pasta dentro do projeto, e a cópia principal a enxerga como arquivos não rastreados. Mantenha as cópias ao lado (../) ou em um diretório separado, ou adicione o caminho ao .gitignore.
• Moveu a pasta manualmente. O vínculo quebra. Mova com git worktree move ../old ../new e, se já moveu, rode git worktree repair na nova pasta.
• Cópia em disco removível desaparece. Para que o prune não apague o registro de uma cópia em um disco desconectado, bloqueie-a: git worktree lock --reason "disco externo" ../shop-usb.
• Submódulos. O suporte a submodules em cópias de trabalho é limitado; depois de criar a cópia, rode git submodule update --init e confira o resultado.

Guia rápido do git worktree

git worktree, stash ou um segundo clone

O stash continua sendo a melhor escolha para interrupções curtas de poucos minutos. Para tudo o que é mais longo, ou quando é preciso manter duas versões abertas, o worktree é mais prático.

Resumo

O git worktree é uma forma simples de trabalhar em várias branches ao mesmo tempo: add cria a pasta, list mostra as cópias, remove e prune fazem a limpeza. O histórico é compartilhado, mas HEAD, índice e arquivos são próprios de cada cópia; uma branch não pode estar aberta em duas cópias. Como as branches funcionam e por que trocar entre elas é tão leve, vemos em detalhes na prática no curso de Git.