Git worktree para múltiplas features simultâneas

1. Introdução ao Git Worktree e o Problema das Múltiplas Features

1.1. O cenário clássico: alternar entre branches com git stash e git checkout

Todo desenvolvedor que trabalha com Git conhece o ritual: você está implementando a feature A, quando chega uma urgência para corrigir um bug na branch main. O ciclo se repete:

git stash
git checkout main
# corrige o bug
git commit -m "fix: corrige validação de email"
git push
git checkout feature-a
git stash pop

Esse fluxo funciona, mas tem um custo cognitivo alto. A cada alternância, você precisa lembrar onde parou, reaplicar mudanças e torcer para não haver conflitos.

1.2. Limitações do modelo single-working-directory

O modelo tradicional de um único diretório de trabalho impõe restrições significativas:

  • Context switching forçado: você não pode manter duas branches abertas simultaneamente
  • Stash frágil: mudanças no stash podem gerar conflitos ao serem reaplicadas
  • Build único: não é possível compilar e testar duas branches ao mesmo tempo
  • Dependência de estado: se você esquece de commitar antes de trocar, perde o progresso

1.3. Conceito fundamental: múltiplos diretórios de trabalho ligados a um único repositório

O Git Worktree resolve esse problema permitindo que você tenha múltiplos diretórios de trabalho (working directories) associados a um único repositório .git. Cada worktree aponta para uma branch diferente, e todos compartilham o mesmo histórico de commits, objetos e referências.

meu-projeto/
├── .git/               # repositório central
├── main/               # worktree da branch main
├── feature-login/      # worktree da branch feature/login
└── hotfix-pagamento/   # worktree da branch hotfix/pagamento

2. Comandos Essenciais do Git Worktree

2.1. git worktree add: criando um novo diretório de trabalho

O comando fundamental para criar um worktree é o add. Você pode criar um worktree para uma branch nova ou existente.

# Criar um worktree para uma nova branch
git worktree add ../meu-projeto-feature-x feature/x

# Criar um worktree a partir de um commit específico
git worktree add ../debug-sprint-23 8f3a2b1

# Criar worktree sem fazer checkout automático
git worktree add --detach ../experimento HEAD~3

2.2. git worktree list: visualizando todos os worktrees ativos

Para ver quais worktrees estão ativos e em qual branch cada um aponta:

git worktree list

# Exemplo de saída:
# /home/user/projeto/main          e4f7a32 [main]
# /home/user/projeto/feature-x     a1b2c3d [feature/x]
# /home/user/projeto/hotfix-y      9f8e7d6 [hotfix/y]

2.3. git worktree remove e prune: limpando worktrees antigos

Quando um worktree não é mais necessário, remova-o:

# Remover um worktree específico
git worktree remove ../meu-projeto-feature-x

# Limpar referências órfãs (worktrees cujo diretório foi deletado manualmente)
git worktree prune

3. Estratégias de Nomenclatura e Organização de Worktrees

3.1. Convenção de diretórios

Uma boa organização facilita a navegação entre worktrees:

projetos/
├── app-core/              # worktree principal (branch main)
├── app-core-feat-login/   # feature/login
├── app-core-hotfix-email/ # hotfix/email
└── app-core-exp-webhook/  # experiment/webhook

3.2. Worktrees com branches já existentes vs. novas branches

# Branch nova (Git cria a branch automaticamente)
git worktree add ../app-core-feat-login feature/login

# Branch existente
git worktree add ../app-core-hotfix-email hotfix/email

# A partir de um remote branch
git worktree add ../app-core-review-pr-42 origin/pr-42

3.3. Trabalhando com branches de mesmo nome

Não é possível ter dois worktrees com a mesma branch checkoutada. Isso previne conflitos. Se precisar, crie branches derivadas:

git checkout -b feature/login-copia feature/login
git worktree add ../app-core-login-copia feature/login-copia

4. Fluxo de Trabalho Prático com Múltiplas Features

4.1. Iniciando duas features simultâneas em worktrees separados

# No diretório principal do projeto
cd ~/projetos/app-core

# Worktree 1: feature de login
git worktree add ../app-core-feat-login feature/login

# Worktree 2: feature de relatório
git worktree add ../app-core-feat-report feature/report

# Worktree 3: hotfix urgente
git worktree add ../app-core-hotfix-payment hotfix/payment

4.2. Desenvolvendo, commitando e testando cada feature isoladamente

Cada worktree funciona como um repositório independente:

# Terminal 1: feature/login
cd ~/projetos/app-core-feat-login
# ... desenvolve a feature
git add .
git commit -m "feat: adiciona autenticação OAuth"

# Terminal 2: hotfix/payment
cd ~/projetos/app-core-hotfix-payment
# ... corrige o bug
git add src/payment.js
git commit -m "fix: corrige cálculo de parcelas"

# Terminal 3: executa testes no main
cd ~/projetos/app-core
npm test

4.3. Fazendo rebase interativo em um worktree sem afetar o outro

# No worktree feature/login
cd ~/projetos/app-core-feat-login
git rebase -i main

# O worktree hotfix/payment continua intacto com seu estado anterior
cd ~/projetos/app-core-hotfix-payment
git log --oneline -5  # histórico inalterado

5. Integração com Ferramentas e IDEs

5.1. Abrindo múltiplas janelas do VS Code ou IntelliJ

# VS Code
code ~/projetos/app-core-feat-login
code ~/projetos/app-core-hotfix-payment

# IntelliJ
idea ~/projetos/app-core-feat-login
idea ~/projetos/app-core-hotfix-payment

5.2. Compilação e testes paralelos em diretórios distintos

# Terminal 1: compilando feature/login
cd ~/projetos/app-core-feat-login && npm run build

# Terminal 2: rodando testes do hotfix
cd ~/projetos/app-core-hotfix-payment && npm test

# Terminal 3: servindo a branch main
cd ~/projetos/app-core && npm start

5.3. Cuidados com arquivos de configuração e dependências compartilhadas

Worktrees compartilham o mesmo repositório .git, mas cada um tem seu próprio diretório de trabalho. Arquivos como node_modules ou .env podem precisar ser instalados separadamente:

# Em cada worktree, instale as dependências
cd ~/projetos/app-core-feat-login && npm install
cd ~/projetos/app-core-hotfix-payment && npm install

6. Gerenciamento de Dependências entre Worktrees

6.1. Quando uma feature depende de outra: cherry-pick entre worktrees

# No worktree feature/report, preciso de um commit da feature/login
cd ~/projetos/app-core-feat-report
git fetch ..app-core-feat-login
git cherry-pick a1b2c3d

6.2. Mantendo branches base sincronizadas via git fetch e git merge

# Em cada worktree, mantenha a base atualizada
cd ~/projetos/app-core-feat-login
git fetch origin
git merge origin/main

cd ~/projetos/app-core-hotfix-payment
git fetch origin
git merge origin/main

6.3. Resolvendo conflitos que surgem em worktrees diferentes

Conflitos são resolvidos localmente em cada worktree. Eles não se propagam para outros worktrees:

# Conflito no worktree feature/login
cd ~/projetos/app-core-feat-login
# Resolve conflitos manualmente
git add .
git commit -m "merge: resolve conflitos com main"

7. Boas Práticas e Armadilhas Comuns

7.1. Evitando worktrees órfãos e branches presas

Sempre remova worktrees que não são mais necessários:

# Antes de deletar, verifique worktrees ativos
git worktree list

# Remova worktrees órfãos
git worktree remove ../app-core-experimento-antigo

7.2. Limpeza periódica com git worktree prune

# Remove referências a worktrees deletados manualmente
git worktree prune

# Verifique worktrees restantes
git worktree list

7.3. Limitações: sistemas de arquivos, hooks e paths absolutos

  • Sistemas de arquivos: worktrees não funcionam bem em sistemas com links simbólicos complexos
  • Hooks: hooks do Git são executados no worktree atual, mas referenciam o .git central
  • Paths absolutos: evite paths absolutos em scripts, pois cada worktree tem seu próprio diretório

8. Casos de Uso Avançados e Alternativas

8.1. Worktrees para revisão de PRs em andamento

# Revisar um PR específico
git worktree add ../app-core-review-pr-42 origin/pr-42
cd ../app-core-review-pr-42
# Analise o código, execute testes, faça sugestões

8.2. Comparação com git clone múltiplo

Aspecto Git Worktree Git Clone
Espaço em disco Compartilha objetos Git Duplica objetos Git
Velocidade de criação Instantâneo Precisa baixar tudo
Sincronização automática Sim (mesmo .git) Não (repositórios independentes)
Risco de conflitos Menor (compartilha locks) Maior (pode divergir)

8.3. Worktrees temporários para experimentos e debugging

# Criar worktree temporário para debug
git worktree add --detach ../debug-crash-report e4f7a32

# Após o debug, remover
git worktree remove ../debug-crash-report

Git Worktree transforma a maneira como lidamos com múltiplas tarefas simultâneas. Ao invés de alternar entre contextos, você mantém cada contexto aberto em seu próprio diretório, permitindo desenvolvimento, teste e deploy paralelos sem conflitos. A curva de aprendizado é pequena, e os ganhos de produtividade são imediatos.

Referências