Tutorial de Git worktree: trabalhe em várias branches sem trocar

Você está trabalhando em uma feature quando um colega pede para você revisar o pull request dele. Dá para dar um stash, trocar de branch e torcer para lembrar de onde parou. Ou pode fazer um commit pela metade só para não perder o que estava fazendo. E ainda tem o hotfix de emergência: produção caiu, e você está no meio de um refactor que mexe em metade do código. Cada troca de contexto dessa custa 10–15 minutos de preparação e quebra totalmente o foco.

Git worktree resolve isso permitindo que você dê checkout em várias branches ao mesmo tempo, cada uma em um diretório separado. Em vez de fazer stash ou commitar trabalho incompleto, você simplesmente dá cd para outro diretório onde outra branch já está em checkout. Trabalhe no hotfix, faça o deploy e depois dê cd de volta para sua feature exatamente como você deixou.

Neste tutorial, vou te mostrar como criar e gerenciar worktrees, evitar armadilhas comuns e integrar isso ao seu fluxo de trabalho diário. Você já deve entender branches e commits no Git e operações básicas de linha de comando. Se quiser revisar os fundamentos de Git antes, recomendo o tutorial Introduction to Git da DataCamp para cobrir o essencial.

O que é Git worktree?

Git worktree é um recurso nativo que cria diretórios de trabalho adicionais vinculados ao mesmo repositório. Seu diretório de trabalho principal é a worktree primária, e cada worktree extra que você cria ganha seu próprio diretório com sua própria branch em checkout. Todas essas worktrees se conectam ao mesmo repositório .git.

Essa arquitetura compartilhada significa que os commits feitos em qualquer worktree aparecem imediatamente no banco de dados do Git, acessível por todas as outras worktrees. Os arquivos em si ficam independentes — editar train.py em uma worktree só afeta aquele diretório até você commitar as mudanças.

Por que não usar terminais diferentes?

Você não consegue abrir vários terminais no mesmo diretório e trabalhar em branches diferentes ao mesmo tempo. O Git só permite uma branch em checkout por diretório. Quando você roda git checkout feature-b em um terminal, os arquivos mudam para todos os terminais apontando para aquele diretório.

Git worktree resolve isso dando a cada branch seu próprio diretório. Cada diretório é totalmente independente, com seus próprios arquivos, processos em execução e artefatos de build. Trocar entre branches vira cd ../outro-diretorio em vez de git checkout outra-branch.

Pré-requisitos do Git worktree

Antes de usar git worktree, confira seu ambiente:

• Git 2.5 ou superior: Rode git --version para verificar. Git worktree saiu em 2015, então a maioria das instalações já tem
• Repositório Git existente: Você precisa de um repositório com pelo menos uma branch
• Familiaridade com terminal: Todas as operações de worktree acontecem no terminal

Veja se o worktree está disponível:

git worktree --help

Se abrir a página de ajuda, está tudo pronto.

Quando usar git worktree

Git worktree é ótimo quando trocar de branch interromperia seu trabalho atual:

• Code reviews: teste as mudanças do colega sem fazer stash da sua feature
• Hotfixes de emergência: corrija bugs em produção sem mexer no seu refactor
• Desenvolvimento em paralelo: trabalhe em duas features independentes sem ficar trocando de branch
• Processos longos: dispare uma suíte de testes de 30 minutos e continue codando em outra worktree

Evite para tarefas rápidas (menos de 10 minutos) em que git checkout é mais simples, ou quando você está focado em uma única atividade sem interrupções previstas.

Criando sua primeira worktree

A melhor forma de entender git worktree é criar uma e ver na prática. Vamos passar pelos comandos básicos, explorar a estrutura que o Git cria e observar como as mudanças fluem entre worktrees.

Configurando um repositório de exemplo

Antes de mergulhar em worktrees, você precisa de um repositório Git para usar. Se você já tem um projeto Python com várias branches, pule para a próxima seção. Caso contrário, vamos criar rapidamente um pipeline de ML simples:

mkdir ml-pipeline
cd ml-pipeline
git init

Crie um README e um script Python:

echo "# ML Pipeline" > README.md
echo "def load_data():" > train.py
echo "    print('Loading training data...')" >> train.py

Verifique se os arquivos foram criados:

ls
# Você deve ver: README.md  train.py

Faça o commit desses arquivos e crie uma branch de feature:

git add .
git commit -m "Initial commit"
git branch feature-preprocessing

Agora você tem um repositório com duas branches: main (sua branch atual) e feature-preprocessing.

Criação básica de worktree

Criar uma worktree para uma branch existente exige só um comando. Vamos dar checkout em feature-preprocessing em um diretório separado:

git worktree add ../ml-pipeline-preprocessing feature-preprocessing

Isso cria um novo diretório chamado ml-pipeline-preprocessing um nível acima do local atual, dá checkout na branch feature-preprocessing lá e vincula ao seu repositório existente.

O Git confirma a criação:

Preparing worktree (checking out 'feature-preprocessing')
HEAD is now at 0a7f986 Initial commit

Para trabalho novo, crie a branch e a worktree de uma vez:

git worktree add -b feature-visualization ../ml-pipeline-viz

A flag -b cria uma nova branch chamada feature-visualization e faz o checkout dela na nova worktree.

Explorando a estrutura da worktree

Com a worktree criada, você agora tem múltiplos diretórios no sistema de arquivos. Para ver todos:

git worktree list

/Users/you/projects/ml-pipeline                  0a7f986 [main]
/Users/you/projects/ml-pipeline-preprocessing    0a7f986 [feature-preprocessing]

A primeira linha mostra sua worktree principal — o diretório original contendo a pasta .git. A segunda linha mostra a worktree vinculada. Ambas exibem o hash do commit atual e a branch em checkout.

Cada diretório de worktree funciona como um repositório Git completo. Você pode navegar até ele, editar arquivos, rodar git status e fazer commits. Worktrees vinculadas não contêm um diretório .git completo — em vez disso, têm um arquivo .git que aponta para o repositório principal. Dentro da pasta .git principal, a pasta worktrees armazena metadados de cada worktree vinculada.

Trabalhando em uma worktree

Navegue até a worktree feature-preprocessing e faça um commit:

cd ../ml-pipeline-preprocessing
cat >> train.py << 'EOF'

def preprocess_features(df):
   """Normalize numeric features."""
   return (df - df.mean()) / df.std()
EOF
git add train.py
git commit -m "Add feature preprocessing function"

O commit acontece normalmente:

[feature-preprocessing 7c8d4e2] Add feature preprocessing function
1 file changed, 3 insertions(+)

Volte para a worktree principal e veja o histórico de commits:

cd ../ml-pipeline
git log --oneline --all

Seu novo commit aparece lá:

7c8d4e2 Add feature preprocessing function
0a7f986 Initial commit

Repare como o commit aparece imediatamente nos dois locais sem comandos adicionais.

Casos de uso do Git worktree

Agora que você sabe criar e trabalhar com worktrees, vamos ver cenários práticos em que elas resolvem problemas reais de desenvolvimento.

Fluxo de code review

Seu colega precisa de feedback no PR. Em vez de fazer stash das suas mudanças e trocar de branch, crie um diretório separado para a revisão:

git worktree add ../ml-pipeline-review pr/update-training
cd ../ml-pipeline-review
pip install -r requirements.txt
python train_model.py --config experiments/baseline.yaml

Teste as mudanças e deixe seu feedback. Ao terminar:

cd ../ml-pipeline
git worktree remove ../ml-pipeline-review

Seu trabalho original fica intocado. Sem stash e sem troca de contexto. Para mais estratégias de code review eficaz, confira o guia de boas práticas de code review da DataCamp.

Hotfixes de emergência

Sem worktrees:

• Guarde seu refactor em algum lugar (stash ou commit WIP)
• Faça checkout da branch main
• Corrija o bug
• Faça o push para produção
• Volte para a branch da feature
• Restaure suas mudanças (unstash ou reverta o commit WIP)
• Recupere o contexto mental do que estava fazendo

Com worktrees:

git worktree add ../ml-pipeline-hotfix main
cd ../ml-pipeline-hotfix

Corrija e faça o deploy:

git add src/data/validation.py
git commit -m "Fix schema validation for nullable timestamp fields"
git push origin main
cd ../ml-pipeline
git worktree remove ../ml-pipeline-hotfix

Você volta ao seu refactor em segundos, com todos os arquivos exatamente como estavam.

Desenvolvimento de features em paralelo

Você está implementando métricas customizadas e um novo data loader — duas features independentes. Crie uma worktree para cada uma:

git worktree add -b feature-custom-metrics ../ml-pipeline-metrics
git worktree add -b feature-streaming-loader ../ml-pipeline-loader

Seu sistema de arquivos agora fica assim:

~/projects/
 ml-pipeline/           [main] - seu trabalho de sempre
 ml-pipeline-metrics/   [feature-custom-metrics]
 ml-pipeline-loader/    [feature-streaming-loader]

Rode as duas features em paralelo — cada uma no seu terminal:

# Terminal 1
cd ~/projects/ml-pipeline-metrics
python experiments/evaluate_custom_metrics.py

# Terminal 2 
cd ~/projects/ml-pipeline-loader
pytest tests/test_data_loader.py -v

Ambos os processos rodam ao mesmo tempo sem conflitos. Quando concluir uma feature, faça o merge e remova a worktree:

cd ~/projects/ml-pipeline
git merge feature-custom-metrics
git worktree remove ../ml-pipeline-metrics

Gerenciando e limpando worktrees

Listando worktrees

Para ver todas as worktrees de um repositório:

git worktree list

/Users/you/projects/ml-pipeline                  a3f9c81 [main]
/Users/you/projects/ml-pipeline-review           b7d4e92 [pr/data-validation]
/Users/you/projects/ml-pipeline-hotfix           a3f9c81 [hotfix/schema-bug]

Cada linha mostra o caminho do diretório, o hash do commit atual e a branch em checkout. A primeira entrada é sempre sua worktree principal (a que contém a pasta .git), e as demais são worktrees vinculadas.

Para scripts ou navegação rápida, extraia apenas os caminhos:

git worktree list | awk '{print $1}'

Removendo worktrees

Quando terminar o trabalho em uma worktree, remova-a corretamente:

cd ~/projects/ml-pipeline
git worktree remove ../ml-pipeline-review

O Git protege contra perda de dados. Se houver mudanças não commitadas:

git worktree remove ../ml-pipeline-review

fatal: '../ml-pipeline-review' contains modified or untracked files, use --force to delete it

Force a remoção se tiver certeza:

git worktree remove --force ../ml-pipeline-review

Se a worktree estiver bloqueada, use --force duas vezes:

git worktree remove --force --force ../ml-pipeline-locked

Se você apagou uma worktree manualmente (rm -rf ou gerenciador de arquivos), o Git ainda a rastreia internamente. Limpe referências obsoletas:

git worktree prune

Faça um ensaio do que seria removido:

git worktree prune --dry-run

Boas práticas e armadilhas comuns

Veja como tirar o máximo das worktrees e como evitar erros frequentes. 

Organização de worktrees

Onde você coloca as worktrees faz diferença. A maioria dos devs cria diretórios irmãos ao repositório principal:

~/projects/
 ml-pipeline/                    # worktree principal
 ml-pipeline-feature-auth/       # worktree vinculada
 ml-pipeline-hotfix-login/       # worktree vinculada

Essa estrutura mantém tudo no mesmo lugar e torna os caminhos previsíveis. O padrão nomedoprojeto-nomedabranch diz exatamente o que cada diretório contém.

Alguns preferem uma pasta dedicada:

~/projects/
 ml-pipeline/                    # worktree principal
 ml-pipeline-worktrees/
   feature-auth/
   hotfix-login/

Escolha uma abordagem e use com consistência. Nomes descritivos como ml-pipeline-user-authentication tornam os diretórios autoexplicativos, enquanto genéricos como ml-pipeline-temp ou ml-pipeline-2 te obrigam a checar o conteúdo. Trate worktrees como temporárias — crie para uma tarefa específica e remova quando terminar.

Armadilhas comuns

Mesma branch em múltiplas worktrees

O Git impede dar checkout da mesma branch em duas worktrees:

git worktree add ../ml-pipeline-duplicate main

fatal: 'main' is already used by worktree at '/Users/you/projects/ml-pipeline'

Essa proteção existe porque você poderia fazer commits conflitantes. Se precisar do mesmo código em dois lugares, crie uma nova branch.

Worktrees esquecidas e espaço em disco

Cada worktree fica no seu disco até você removê-la explicitamente. Worktrees antigas se acumulam; projetos podem juntar 15+ worktrees esquecidas, consumindo gigabytes.

Cada worktree contém uma cópia completa dos arquivos do repositório. Um repositório de 500 MB com 5 worktrees consome 2,5 GB. Remova worktrees quando acabar:

git worktree list
git worktree remove ../ml-pipeline-old-feature

Aninhar worktrees

Não crie uma worktree dentro do diretório de outra worktree. O Git até permite, mas isso confunde a estrutura de diretórios e torna a limpeza sujeita a erros.

Otimização do fluxo

Aliases no shell economizam tempo se você cria worktrees com frequência:

alias gwl='git worktree list'
alias gwa='git worktree add'
alias gwr='git worktree remove'

Para configurações mais complexas, escreva uma função que crie a worktree e configure seu ambiente de desenvolvimento em um passo:

wt() {
 git worktree add "../${PWD##*/}-$1" -b "$1"
 cd "../${PWD##*/}-$1"
 python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
}

O ${PWD##*/} extrai o nome do diretório atual. Rodar wt feature-logging a partir de ml-pipeline cria ml-pipeline-feature-logging, navega para lá e configura um ambiente virtual Python com as dependências.

Criar uma worktree vira um único comando:

wt feature-custom-metrics

Adapte para sua linguagem: substitua a configuração de Python por bundle install para Ruby, cargo build para Rust, ou npm install para Node.js.

Seu editor ou IDE funciona com worktrees sem configuração especial. Cada worktree é só um diretório, então abra como qualquer pasta de projeto. A maioria dos editores modernos permite abrir múltiplas raízes de projeto ao mesmo tempo — você pode ter três worktrees na mesma janela e alternar entre elas na barra lateral.

Worktrees avançadas: desenvolvimento paralelo com apoio de IA

Se você usa assistentes de código com IA, worktrees liberam um fluxo paralelo poderoso. Essa abordagem ganhou força entre devs e times em 2024–2025.

Crie worktrees separadas para tarefas diferentes:

git worktree add -b feature-add-logging ../ml-pipeline-logging
git worktree add -b feature-optimize-preprocessing ../ml-pipeline-optim
git worktree add -b bugfix-memory-leak ../ml-pipeline-bugfix

Abra um painel de terminal para cada worktree e inicie seu assistente de IA:

# Pane 1
cd ~/projects/ml-pipeline-logging
claude

# Pane 2
cd ~/projects/ml-pipeline-optim
claude

# Pane 3
cd ~/projects/ml-pipeline-bugfix
claude

Cada instância da IA trabalha em uma feature diferente sem interferência. Times relatam concluir trabalho em horas que antes levavam dias. Por exemplo, a incident.io roda 4–5 agentes do Claude Code em paralelo usando esse padrão. Em um caso, o Claude estimou uma melhoria de UI em 2 horas, mas terminou em 10 minutos.

Pontos de atenção:

• Consumo de tokens: múltiplas sessões de IA usam mais créditos de API e podem atingir limites de taxa
• Overhead de setup: cada worktree precisa do seu próprio ambiente e dependências
• Carga cognitiva: gerenciar várias conversas em tarefas diferentes

Funciona bem para features grandes e independentes (30+ minutos cada), que não mexem nos mesmos arquivos, e quando você tem cota de API suficiente. Evite para correções rápidas, features muito acopladas ou quando estiver próximo dos limites de taxa da API.

Conclusão

Lembra do cenário do início — um colega precisa de review no PR enquanto você está no meio de uma feature. Agora você sabe a solução: git worktree add ../ml-pipeline-review pr/branch-name e depois cd para começar a revisar. Sua feature fica intocada. Sem stash, sem commit pela metade, sem esforço mental para reconstruir o contexto quando voltar. Dois diretórios, duas branches, zero atrito.

Git worktree não adiciona complexidade ao seu fluxo — ele remove. Cada worktree é só um diretório com uma branch em checkout. Mas essa simplicidade libera algo poderoso: a capacidade de alternar de contexto instantaneamente entre tarefas sem a carga cognitiva de fazer stash, dar checkout e reconstruir seu modelo mental. 

Quando você precisar integrar worktrees a fluxos colaborativos como pull requests e code reviews, a trilha de habilidades GitHub Foundations da DataCamp cobre as práticas essenciais para trabalhar bem em times distribuídos.