Se você já perdeu tempo com essa sequência:
git stash
git checkout outra-branch
# resolve o problema urgente
git checkout branch-original
git stash pop
...só pra descobrir depois que esqueceu o que tinha no stash, ou que o venv/node_modules da outra branch estava desatualizado — este artigo é pra você.
O problema
Um repositório Git tradicional tem uma única pasta de trabalho ligada a uma branch por vez. Trocar de branch significa trocar todo o conteúdo dessa pasta. Isso funciona bem quando você faz uma coisa de cada vez, mas quebra assim que você precisa:
- Revisar um PR urgente enquanto está no meio de uma feature grande
- Rodar testes de uma branch enquanto edita outra
- Manter ambientes de dependências diferentes (versões de libs,
.env) para features distintas sem reinstalar tudo a cada troca
A saída mais comum é o stash, mas ele é frágil: some da vista, acumula, e é fácil esquecer o que tinha ali dentro.
A solução: git worktree
O git worktree permite ter várias pastas de trabalho simultâneas, cada uma vinculada a uma branch diferente, todas compartilhando o mesmo histórico de commits (o .git).
Pense em uma biblioteca central (o histórico do repositório) com várias mesas de leitura (as worktrees), cada uma com um livro diferente aberto. Você não precisa fechar um livro pra abrir outro.
O que é compartilhado, o que é separado
| Compartilhado entre worktrees | Separado por worktree |
|---|---|
| Histórico de commits | Arquivos da working directory |
| Objetos do Git (blobs, trees) | Arquivos não versionados (.env, venv, node_modules) |
| Configuração do repositório | Saída do git status
|
Um commit feito em uma worktree aparece imediatamente no git log das outras — mas os arquivos físicos de cada pasta continuam independentes.
Colocando em prática
Criando uma worktree com branch nova
git worktree add ../meu-projeto-feature-x -b feature/nome-da-feature
Isso cria a pasta ../meu-projeto-feature-x, já com uma branch nova feature/nome-da-feature criada a partir do commit atual.
Criando uma worktree para uma branch que já existe
git worktree add ../meu-projeto-hotfix feature/hotfix-urgente
Útil quando a branch já veio de um colega ou de um PR aberto.
Listando as worktrees ativas
git worktree list
Saída parecida com:
/home/user/meu-projeto abc1234 [main]
/home/user/meu-projeto-feature-x def5678 [feature/nome-da-feature]
/home/user/meu-projeto-hotfix ghi9012 [feature/hotfix-urgente]
Removendo uma worktree depois do merge
git worktree remove ../meu-projeto-feature-x
Se a pasta tiver mudanças não commitadas, o Git avisa e pede --force.
Estrutura de pastas sugerida
~/projetos/meu-projeto/ # repo principal (main/develop)
~/projetos/meu-projeto-feature-x/ # worktree da feature X
~/projetos/meu-projeto-hotfix/ # worktree do hotfix urgente
Cada pasta pode ter seu próprio ambiente virtual, seu próprio servidor rodando em uma porta diferente, sua própria instância do editor aberta — sem um interferir no outro.
Convenção de nomes ligada ao board
Se seu time usa um board tipo Jira/Linear, vale manter o ID do card no nome da branch (e da worktree):
git worktree add ../meu-projeto-proj-123 -b feature/PROJ-123-descricao-curta
Isso facilita rastrear no PR, no CI e em qualquer extração de métricas de fluxo (lead time, deployment frequency) que você faça a partir do histórico de branches.
Dicas práticas
1. Evite worktrees de vida muito longa. O worktree resolve o problema de contexto simultâneo, não o de branches gigantes. Combine com features pequenas e merges frequentes — se uma feature for demorar semanas, considere feature flags em vez de manter a branch (e a worktree) viva por muito tempo.
2. Cuidado com portas e serviços locais. Se cada worktree sobe um servidor de desenvolvimento, defina portas diferentes por ambiente (.env.local com PORT=8001, por exemplo) pra evitar conflito.
3. .gitignore continua valendo por pasta. Arquivos como .env, venv/, node_modules/ não são compartilhados automaticamente — cada worktree precisa da própria cópia (ou de um pip install / npm install local).
4. Worktrees podem viver fora do diretório do repo. Não precisam ficar como subpastas; o exemplo usa ../ só por convenção de organização.
Por que isso importa
A alternativa mais comum ao worktree — múltiplos clones separados do mesmo repositório — resolve o problema de paralelismo, mas duplica o histórico completo em disco e obriga a sincronizar remotes manualmente entre os clones. O worktree resolve o mesmo problema mantendo um único .git como fonte de verdade, com o custo de espaço em disco apenas dos arquivos de trabalho, não do histórico inteiro.
Se seu fluxo de trabalho envolve alternar entre features, revisar PRs no meio de outra tarefa, ou manter hotfixes prontos pra aplicar sem abandonar o que está em andamento, o git worktree provavelmente vai economizar mais tempo do que qualquer alias de stash que você já criou.
Já usa git worktree no seu fluxo? Como você organiza as pastas e os ambientes de cada worktree? Comenta aí.
Top comments (0)