Worktrees: múltiplas branches ao mesmo tempo

1. O que são Worktrees e Por Que Usá-las?

1.1. Definição: múltiplas cópias de trabalho do mesmo repositório

Worktrees são uma funcionalidade do Git que permite ter múltiplas cópias de trabalho (working directories) associadas a um único repositório. Cada worktree possui seu próprio diretório, índice, arquivos modificados e branch ativa, mas compartilham o mesmo repositório .git principal. Isso significa que você pode ter várias branches checkout simultaneamente, cada uma em seu próprio diretório, sem interferência entre elas.

1.2. Problema resolvido: evitar git stash e trocas constantes de branch

O fluxo tradicional com git checkout exige que você:
- Salve ou descarte alterações com git stash
- Troque de branch
- Trabalhe em uma única branch por vez
- Recupere o stash ao voltar

Com worktrees, você elimina esse ciclo. Cada branch tem seu próprio espaço de trabalho isolado. Você pode:
- Manter a branch main limpa em uma worktree
- Trabalhar em uma feature em outra worktree
- Aplicar um hotfix em uma terceira worktree
Tudo simultaneamente, sem stashes ou conflitos de estado.

1.3. Comparação com alternativas

Alternativa Problemas
Clonar o repositório várias vezes Duplica o armazenamento, perde referências compartilhadas, requer sincronização manual
git checkout com stash Perde contexto, propenso a erros, limita produtividade
Worktrees Compartilham objetos, referências e configuração; economizam espaço e mantêm consistência

2. Comandos Fundamentais para Gerenciar Worktrees

2.1. git worktree add: criando uma nova worktree

# Criar worktree para branch existente
git worktree add ../projeto-feature feature-x

# Criar worktree com nova branch
git worktree add -b nova-feature ../nova-feature main

# Criar worktree a partir de um commit específico
git worktree add ../experimento abc1234

2.2. git worktree list: visualizando todas as worktrees ativas

$ git worktree list
/home/user/projeto         abc1234 [main]
/home/user/projeto-feature def5678 [feature-x]
/home/user/nova-feature    fedcba9 [nova-feature]

2.3. git worktree remove e prune: limpando worktrees antigas

# Remover worktree específica
git worktree remove ../projeto-feature

# Limpar referências de worktrees removidas manualmente
git worktree prune

3. Criando Worktrees na Prática

3.1. Criar worktree para uma branch existente

cd /home/user/meu-projeto
git branch -a
# * main
#   feature-login
#   hotfix-urgente

git worktree add ../meu-projeto-hotfix hotfix-urgente
# Saída: Preparing worktree (checking out 'hotfix-urgente')
# Agora temos /home/user/meu-projeto-hotfix com a branch hotfix-urgente

3.2. Criar worktree com uma nova branch (flag -b)

git worktree add -b feature-pagamento ../feature-pagamento main
# Cria nova branch 'feature-pagamento' a partir de 'main' e faz checkout em ../feature-pagamento

3.3. Criar worktree a partir de um commit ou tag específica

# A partir de um hash de commit
git worktree add ../debug-build a1b2c3d4

# A partir de uma tag
git worktree add ../versao-antiga v1.0.0

# A partir de uma remote branch
git worktree add ../pr-review origin/pull-request/42

4. Navegação e Organização de Diretórios

4.1. Estrutura de pastas gerada pelo comando add

meu-projeto/                  # Repositório principal (main)
├── .git/                     # Pasta .git compartilhada
├── src/
├── tests/
└── ...

../feature-pagamento/         # Worktree adicional
├── .git                      # Arquivo apontando para ../meu-projeto/.git
├── src/
├── tests/
└── ...

Cada worktree tem um arquivo .git que contém:

gitdir: /caminho/absoluto/para/meu-projeto/.git/worktrees/feature-pagamento

4.2. Como acessar e trabalhar em cada worktree independentemente

# Terminal 1: Trabalhando na worktree principal
cd ~/meu-projeto
git status  # Mostra estado da branch main

# Terminal 2: Trabalhando na worktree de feature
cd ~/feature-pagamento
git status  # Mostra estado da branch feature-pagamento

# Ambos podem compilar, testar e modificar arquivos simultaneamente

4.3. Dicas de nomenclatura para manter a organização

# Padrão recomendado: <nome-do-repo>-<nome-da-branch>
git worktree add ../meu-projeto-feature-pagamento feature-pagamento
git worktree add ../meu-projeto-hotfix-seguranca hotfix-seguranca
git worktree add ../meu-projeto-experimento-webpack experimento-webpack

# Ou use subpastas organizadas por tipo
mkdir -p ../worktrees
git worktree add ../worktrees/features/pagamento feature-pagamento
git worktree add ../worktrees/hotfixes/seguranca hotfix-seguranca

5. Limitações e Cuidados Essenciais

5.1. Restrição: uma branch só pode estar em uma worktree por vez

# Tentar fazer checkout da mesma branch em outra worktree causa erro:
$ git worktree add ../copia-feature feature-pagamento
fatal: 'feature-pagamento' is already checked out at '/home/user/feature-pagamento'

5.2. Conflitos com hooks, arquivos ignorados e estado sujo

  • Hooks: São compartilhados entre todas as worktrees. Um hook pre-commit em uma worktree afeta todas.
  • Arquivos ignorados: Cada worktree tem seu próprio .gitignore local (se houver) e seu próprio conjunto de arquivos ignorados.
  • Estado sujo: Se uma worktree tem arquivos não rastreados ou modificações, você não pode removê-la sem forçar.
# Tentar remover worktree com estado sujo
git worktree remove ../feature-pagamento
fatal: 'feature-pagamento' contains modified or untracked files, use --force to delete it

# Forçar remoção (cuidado!)
git worktree remove --force ../feature-pagamento

5.3. Cuidados com operações que afetam o repositório principal

# `git gc` no repositório principal pode limpar objetos referenciados por worktrees
# Use com cautela
git gc --prune=now  # Pode quebrar worktrees

# `git fetch` funciona normalmente em qualquer worktree
git fetch origin  # Atualiza referências para todas as branches

# `git rebase` em branches compartilhadas requer atenção
# Se você rebase uma branch que está em outra worktree, precisa atualizar manualmente

6. Casos de Uso Avançados

6.1. Revisão de Pull Requests com worktrees separadas

# Para revisar um PR específico
git worktree add ../pr-review-42 origin/pr/42
cd ../pr-review-42
git checkout -b review-42 origin/pr/42

# Após revisão, remova a worktree
cd ..
git worktree remove pr-review-42

6.2. Trabalhando em hotfix e feature simultaneamente

# Worktree 1: Hotfix crítico
git worktree add ../projeto-hotfix main
cd ../projeto-hotfix
# Aplica correção, commit, push

# Worktree 2: Feature em desenvolvimento
cd ~/projeto
git worktree add ../projeto-feature feature-x
cd ../projeto-feature
# Continua desenvolvimento normalmente

# Worktree 3: Testes em outra branch
git worktree add ../projeto-teste branch-experimento

6.3. Worktrees temporárias para experimentos e testes

# Criar worktree descartável para testar uma ideia
git worktree add ../experimento-temp main
cd ../experimento-temp
# Testar alterações radicais sem medo

# Quando terminar, descarte tudo
cd ..
rm -rf experimento-temp
git worktree prune  # Limpa referência

7. Integração com Ferramentas e Fluxos de Trabalho

7.1. Uso com IDEs e terminais múltiplos

  • VS Code: Abra cada worktree como um projeto separado (File > Open Folder). Use múltiplas janelas.
  • IntelliJ: Crie módulos separados para cada worktree ou use projetos independentes.
  • Terminal: Mantenha um terminal por worktree com cd para o diretório específico.

7.2. Scripts de automação para criar/remover worktrees

#!/bin/bash
# Script: criar-worktree.sh
# Uso: ./criar-worktree.sh feature-nova

BRANCH_NAME=$1
WORKTREE_PATH="../meu-projeto-$BRANCH_NAME"

if [ -z "$BRANCH_NAME" ]; then
    echo "Uso: $0 <nome-da-branch>"
    exit 1
fi

git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH" main
echo "Worktree criada em: $WORKTREE_PATH"
echo "Branch: $BRANCH_NAME"

7.3. Worktrees em equipe: boas práticas para evitar confusão

  • Comunique as worktrees ativas: Use git worktree list para verificar antes de criar novas.
  • Padronize nomes de diretórios: Defina uma convenção como <projeto>-<tipo>-<descricao>.
  • Limpe worktrees obsoletas: Execute git worktree prune regularmente.
  • Evite worktrees aninhadas: Não crie worktrees dentro de outras worktrees.
  • Documente no README: Inclua instruções sobre como o time deve usar worktrees no projeto.

Referências