Exemplos de Git Worktree

Exemplos práticos de copiar e colar para o fluxo de trabalho diário com worktree: criar, fazer checkout, mesclar, buscar e remover. Todos os comandos assumem um Git recente (2.23+) para que git switch funcione ao lado do mais antigo git checkout.

Receita

Cartão de referência rápida -- pronto para copiar e colar.

# Create + checkout an existing branch in a new worktree
git worktree add ../feature-branch feature-branch
 
# Create a new branch and check it out in a new worktree
git worktree add ../new-feature -b new-feature
 
# Detached HEAD on a specific commit or tag
git worktree add ../hotfix abc1234
 
# List worktrees and the branch each one has checked out
git worktree list
 
# Remove a worktree once you're done
git worktree remove ../feature-branch
 
# Clean up stale entries after a folder was deleted manually
git worktree prune

Quando usar isso: Qualquer fluxo de trabalho baseado em worktree -- desenvolvimento de features, isolamento de hotfixes, revisão de PR, comparação lado a lado.

Exemplo de Trabalho

Ciclo de vida completo de uma feature

# 1. Start the feature in a new worktree on a new branch
git worktree add ../my-feature -b my-feature
 
# 2. Move into it and work normally
cd ../my-feature
# ...edit files, run tests, commit...
git add .
git commit -m "feat: scaffold my-feature"
 
# 3. Walk back to main and merge
cd ../main-repo
git switch main
git pull origin main
git merge my-feature
 
# 4. Push and clean up
git push origin main
git worktree remove ../my-feature
git branch -d my-feature

O que isso demonstra:

• Worktrees e branches compartilham o histórico imediatamente -- nenhum ciclo de push/pull é necessário entre eles.
• A mesclagem ocorre no worktree de destino (aquele cujo branch receberá as alterações).
• Remover um worktree deixa o branch intacto; excluir o branch é um passo separado e deliberado.

Mergulho Profundo

1. Criando e fazendo checkout de branches em worktrees

Os comandos principais -- comece aqui.

# Create a new worktree and checkout an existing branch
git worktree add ../feature-branch feature-branch
 
# Create a new branch AND check it out in a new worktree
git worktree add ../new-feature -b new-feature
 
# Checkout a specific commit or tag (detached HEAD)
git worktree add ../hotfix abc1234
 
# Modern alternative to git checkout (safer for branches)
git switch <branch>          # Inside a worktree
git switch -c <new-branch>   # Create + switch

Dica: Prefira git switch em vez de git checkout para operações de branch (introduzido no Git 2.23+). git checkout ainda funciona, mas é sobrecarregado com comportamento de restauração de arquivos, o que pode ser problemático se você digitar incorretamente um nome de branch.

2. Listando e gerenciando branches entre worktrees

git branch -a                # All branches (local + remote)
git branch -v                # With last commit info
git worktree list            # Which branch each worktree has checked out
git worktree list --porcelain # Machine-readable for scripts

git worktree list é a resposta para "espere, onde eu deixei aquele hotfix?"

3. Mesclando branches entre worktrees (fluxo de trabalho comum)

A mesclagem ocorre no worktree de destino -- geralmente aquele com main ou um branch de release em checkout.

# From your main worktree:
cd ../main-project
git switch main              # or: git checkout main
git pull origin main         # Always update first
 
# Merge a completed feature branch (developed in another worktree)
git merge feature-branch     # Fast-forward or create a merge commit
 
# Merge with options
git merge --no-ff feature-branch     # Always create a merge commit
git merge --squash feature-branch    # Squash changes (then commit manually)
 
# Rebase instead, for a cleaner history
git switch feature-branch    # Switch into the feature branch's worktree first
git rebase main
git switch main
git merge feature-branch     # Now a clean fast-forward

Exemplo de mesclagem entre worktrees:

1. Termine o trabalho e comite dentro de ../feature-worktree.
2. Volte para o worktree principal com cd.
3. git merge feature-branch -- o ponteiro do branch foi atualizado automaticamente pelo commit no outro worktree.

Sem push, sem pull, sem viagem de ida e volta ao remoto. A pasta .git compartilhada torna isso transparente.

4. Buscando, puxando e atualizando

git fetch origin             # Updates remote refs -- visible from all worktrees
git pull origin main         # Fetch + merge into the worktree you ran this in
 
# Update a feature worktree's base
cd ../my-feature
git fetch origin
git rebase origin/main       # Replay your feature commits on top of latest main

Ponto chave: git fetch atualiza o estado na pasta .git compartilhada, então cada worktree vê as novas refs remotas imediatamente. git pull afeta apenas o branch em checkout no worktree onde você o executou.

5. Outros comandos úteis relacionados a checkout/merge

Fazer cherry-pick de um commit de outro branch ou worktree:

git cherry-pick abc1234

Comparar branches sem alternar:

git diff main..feature-branch

Resolver conflitos durante uma mesclagem (fluxo padrão):

git status                   # See conflicted files
# Edit each file to resolve markers
git add <file>
git merge --continue

Abortar uma mesclagem:

git merge --abort

Para o guia completo de resolução de conflitos, veja Lista de Verificação de Resolução de Conflitos de Merge.

6. Exemplo de ciclo de vida completo

# 1. Start feature
git worktree add ../my-feature -b my-feature
 
# 2. Work and commit in that directory...
cd ../my-feature
# ...code, test, commit...
 
# 3. Merge back
cd ../main-repo
git switch main
git merge my-feature
 
# 4. Clean up
git worktree remove ../my-feature
git branch -d my-feature     # Optional: delete branch

7. Interrupções de hotfix em feature em andamento

# You're deep in feature work in ../my-feature, and prod breaks.
# Don't stash. Don't switch branches. Just spin up a hotfix worktree.
 
cd ~/projects/main-repo
git fetch origin
git worktree add ../hotfix -b hotfix/login-500 origin/main
 
cd ../hotfix
# ...debug, fix, commit, push, open PR...
git push -u origin hotfix/login-500
 
# Once the PR is merged, clean up
cd ~/projects/main-repo
git worktree remove ../hotfix
git branch -D hotfix/login-500   # If the remote branch was deleted on merge
 
# Walk back to your feature work, exactly as you left it
cd ../my-feature

8. Revisão de PR sem perturbar seu trabalho

# A teammate pushed a branch you need to review
git fetch origin
git worktree add ../review-pr-482 origin/feature/teammate-thing
 
cd ../review-pr-482
npm install
npm run dev
# ...read code, test it, leave PR comments...
 
# Tear it down when done
cd ../main-repo
git worktree remove ../review-pr-482

9. Comparação lado a lado

# Run two implementations at once for a real comparison
git worktree add ../approach-a -b experiment/approach-a
git worktree add ../approach-b -b experiment/approach-b
 
# Two terminal windows, two dev servers on different ports, both editable.
# When done, keep the winner, remove the loser.
git worktree remove ../approach-b
git branch -D experiment/approach-b

Dicas Pro e Armadilhas

• Sempre comite ou use stash nas alterações antes de remover um worktree. O Git se recusa por padrão; use --force apenas quando tiver certeza.
• Execute git worktree prune após excluir manualmente um diretório de worktree.
• git fetch uma vez, veja atualizações em todos os lugares -- a pasta .git compartilhada torna as refs instantaneamente visíveis em todos os worktrees.
• Para mesclagens complexas, considere git mergetool -- ele funciona da mesma forma em qualquer worktree.
• Submódulos precisam de git submodule update --init --recursive por worktree.

Armadilhas

Coisas que vão te morder. Cada armadilha inclui o que dá errado, por que acontece e a correção.

• fatal: '<branch>' is already checked out at ... -- Você tentou adicionar um worktree em um branch que já está em checkout em outro lugar. Correção: Ou trabalhe no worktree existente, ou crie um novo branch a partir dele: git worktree add ../scratch -b scratch <branch>.

• Conflitos de rebase em um worktree de feature, e depois esquecer de atualizar o alvo da mesclagem -- Você fez rebase de feature em origin/main dentro de ../my-feature, mas no seu worktree principal você esqueceu de executar git pull primeiro. Correção: Sempre execute git fetch + git pull no worktree de destino antes de mesclar.

• git checkout <branch> altera arquivos no worktree atual -- Você pretendia adicionar um worktree, mas digitou o comando antigo. Correção: Use git worktree add para criar um novo worktree; git switch/git checkout apenas muda o atual.

• Stashes se aplicam entre worktrees e te surpreendem -- Você usou stash no worktree A, depois git stash pop no worktree B aplica os arquivos errados. Correção: Stashes são compartilhados. Nomeie-os (git stash push -m "feature X wip") e revise com git stash list antes de usar pop.

• Force-push de um branch de um worktree quebra mesclagens em outro -- Worktree A faz force-push de feature, worktree B ainda tem os commits antigos em checkout e um git pull aciona uma recusa confusa de fast-forward. Correção: Coordene force-pushes; execute novamente git fetch + git reset --hard origin/feature no outro worktree se tiver certeza.

• node_modules fora de sincronia entre worktrees -- Você atualizou uma dependência no worktree A; o worktree B ainda tem a versão antiga instalada. Correção: Execute npm install (ou seu equivalente) novamente para cada worktree após alterações de dependência.

• Commit de merge vai para o branch errado -- Você executou git merge feature-branch de um worktree que tinha develop em checkout, não main. Correção: Execute git branch --show-current antes de mesclar. Use git reset --hard ORIG_HEAD para desfazer a mesclagem se ela ainda não foi enviada.

Alternativas

Outras maneiras de resolver o mesmo problema -- e quando cada uma é a melhor escolha.

FAQs

git fetch origin
git worktree add ../review origin/feature/teammate-branch

cd ../my-feature
git fetch origin
git rebase origin/main

git cherry-pick <sha>

git diff main..feature-branch
git log main..feature-branch --oneline

git worktree prune

git worktree move ../old-path ../new-path

Relacionados

• Introdução ao Git Worktrees -- O modelo mental e comandos básicos
• Mesclagem e Rebase -- Combinando branches entre worktrees
• Lista de Verificação de Resolução de Conflitos de Merge -- Quando uma mesclagem entre worktrees entra em conflito
• Comandos Essenciais do Git -- Os comandos do dia a dia em que se baseia o fluxo de trabalho de worktree