Git worktrees: trabalhando em múltiplas branches ao mesmo tempo

1. Introdução ao conceito de Git Worktrees

Desenvolvedores que trabalham com Git frequentemente enfrentam um problema comum: a necessidade de alternar entre diferentes branches para revisar código, corrigir bugs urgentes ou testar funcionalidades paralelas. O método tradicional com git checkout ou git switch exige que você salve ou faça stash das alterações atuais, perca o contexto mental e, muitas vezes, enfrente conflitos ao retornar.

Git worktrees resolvem esse problema permitindo que você tenha múltiplas cópias do mesmo repositório, cada uma apontando para uma branch diferente, em diretórios separados. Diferente de clones completos, worktrees compartilham o mesmo repositório base (objects, refs), economizando espaço em disco e mantendo a sincronia entre as branches.

As vantagens são significativas: isolamento total de contexto (cada worktree tem seu próprio diretório de trabalho e staging area), economia de tempo (sem necessidade de stash ou commits temporários) e redução de conflitos (cada branch opera em seu próprio espaço).

2. Configuração básica e criação de worktrees

Para criar um worktree, utilizamos o comando git worktree add. A sintaxe básica é:

git worktree add <caminho> <branch>

Vamos a exemplos práticos. Suponha que você está no diretório do projeto meu-projeto:

# Criar um worktree para uma branch existente
git worktree add ../meu-projeto-hotfix hotfix/login-error

# Criar um worktree com uma nova branch (criada a partir do HEAD atual)
git worktree add -b feature/nova-api ../meu-projeto-feature

# Criar um worktree a partir de um commit específico
git worktree add ../meu-projeto-teste v2.0.0

Para verificar todos os worktrees ativos:

git worktree list

A saída mostrará algo como:

/home/user/meu-projeto          (main)
/home/user/meu-projeto-hotfix   (hotfix/login-error)
/home/user/meu-projeto-feature  (feature/nova-api)

3. Navegação e gerenciamento entre worktrees

Uma vez criados, cada worktree é um diretório independente. Para alternar entre eles, basta navegar com cd:

cd ../meu-projeto-hotfix
git status  # mostra o estado da branch hotfix/login-error

cd ../meu-projeto-feature
git status  # mostra o estado da branch feature/nova-api

Para remover um worktree quando não for mais necessário:

# Remove a referência do worktree
git worktree remove ../meu-projeto-hotfix

# Se houver alterações não commitadas, force a remoção
git worktree remove ../meu-projeto-hotfix --force

Cuidado com worktrees órfãos: se você deletar uma branch que está sendo usada por um worktree, o worktree ainda existirá, mas apontará para um commit órfão. Use git worktree list --porcelain para verificar o estado detalhado.

4. Fluxo de trabalho prático com múltiplas branches

Cenário 1: Revisão de código enquanto desenvolve

# No worktree principal (main)
cd ~/projeto
git checkout main

# Crie um worktree para revisar um PR
git worktree add ../projeto-review feature/nova-funcionalidade

# No terminal 1: continue desenvolvendo no main
cd ~/projeto
git add novo-arquivo.py
git commit -m "Adiciona funcionalidade X"

# No terminal 2: revise o código da feature
cd ~/projeto-review
git log --oneline -5
code .  # abre o editor para revisão

Cenário 2: Correção urgente sem interromper feature

# Você está trabalhando em uma feature complexa
git worktree add ../projeto-bugfix hotfix/erro-critico

# Corrija o bug no worktree separado
cd ../projeto-bugfix
git add fix.py
git commit -m "Corrige erro crítico no login"
git push origin hotfix/erro-critico

# Volte para o trabalho original sem nenhum stash
cd ../projeto
git status  # tudo intacto

Cenário 3: Testes paralelos de versões

# Teste a versão estável
git worktree add ../projeto-v2 v2.0.0

# Teste a versão de desenvolvimento
git worktree add ../projeto-dev develop

# Execute testes em paralelo
cd ../projeto-v2 && npm test &
cd ../projeto-dev && npm test &

5. Worktrees e hooks: integração com automações

Uma questão comum é como os hooks se comportam em worktrees. Por padrão, cada worktree tem seu próprio diretório .git/hooks, mas eles podem ser configurados para compartilhar hooks.

Para configurar hooks compartilhados:

# Crie um diretório central de hooks
mkdir -p ~/projeto/.githooks

# Configure o Git para usar esse diretório
git config core.hooksPath .githooks

# Este hook será executado em todos os worktrees
cat > ~/projeto/.githooks/post-checkout << 'EOF'
#!/bin/bash
echo "Worktree criado em $(pwd) na branch $(git rev-parse --abbrev-ref HEAD)"
EOF
chmod +x ~/projeto/.githooks/post-checkout

Exemplo prático: validação automática ao criar worktree

# Hook post-checkout que valida o ambiente
cat > ~/projeto/.githooks/post-checkout << 'EOF'
#!/bin/bash
if [ -f "package.json" ]; then
    npm install --silent
fi
if [ -f "requirements.txt" ]; then
    pip install -r requirements.txt --quiet
fi
echo "Ambiente configurado para $(git rev-parse --abbrev-ref HEAD)"
EOF

6. Boas práticas e armadilhas comuns

Evite worktrees aninhados: criar worktrees dentro de worktrees pode causar confusão. Mantenha todos os worktrees no mesmo nível de diretório.

Limpeza periódica: worktrees antigos ocupam espaço e poluem a saída de git worktree list. Execute regularmente:

# Remove worktrees cujas branches foram deletadas
git worktree prune

# Verifique worktrees antigos (mais de 30 dias)
git worktree list | awk '{print $2}' | xargs -I {} sh -c 'echo "{} - $(git log -1 --format=%ci {})"'

Limitações conhecidas:
- Repositórios compartilhados via rede (NFS, SMB) podem ter problemas de locking
- Alguns sistemas de arquivos não suportam links simbólicos necessários para worktrees
- Ferramentas de CI/CD podem não limpar worktrees corretamente

7. Comparação com alternativas

Característica Git Worktree Git Stash Clone Completo
Isolamento Total Parcial Total
Espaço em disco Mínimo Nenhum Máximo
Sincronia automática Sim Não Não
Perda de contexto Nenhuma Alta Nenhuma
Complexidade Média Baixa Alta

Quando usar stash: Para mudanças rápidas e temporárias (menos de 5 minutos).

Quando preferir clone: Quando precisa de configurações completamente diferentes (versões de dependências, sistemas operacionais).

Vantagens dos worktrees sobre múltiplos clones: Economia de espaço (compartilham objetos Git), sincronia automática (mesmo repositório base), facilidade de gerenciamento (comandos unificados).

8. Conclusão e próximos passos

Git worktrees são uma ferramenta poderosa para desenvolvedores que precisam gerenciar múltiplos contextos simultaneamente. Eles eliminam a necessidade de stash, reduzem conflitos e permitem um fluxo de trabalho mais fluido.

Para aprofundar-se, explore comandos avançados como:

# Automação com scripts
git worktree prune --dry-run  # Simula a limpeza

# Criar worktree a partir de uma branch remota
git worktree add --track ../projeto-origem origin/feature-x

# Script para limpeza automática semanal
0 0 * * 0 cd ~/projeto && git worktree prune --expire 30.days

Integre worktrees com suas ferramentas de CI/CD para ambientes de teste isolados, ou utilize em conjunto com Docker para ambientes completamente independentes. A prática leva à maestria — experimente criar worktrees em seu próximo projeto e descubra como eles podem transformar seu fluxo de trabalho.

Referências