Checklist de Resolução de Conflitos de Merge

Um guia passo a passo para resolver conflitos de merge ou rebase com segurança. Execute as etapas na ordem -- pular etapas é o que leva à perda de árvores de trabalho limpas. Cada etapa tem uma saída de emergência (--abort) para que você possa desistir a qualquer momento até o commit final.

Como Usar Este Checklist

• Trate cada etapa como um ponto de verificação. Não comece a etapa N+1 até que a etapa N esteja verde.
• Se algo parecer errado (trabalho não commitado, arquivos inesperados, um branch desconhecido), PARE e execute a etapa 18 (--abort).
• A maioria dos conflitos é resolvida nas etapas 8-13. As etapas 1-7 previnem conflitos; as etapas 14-20 verificam a resolução.

Fase 1: Preparar (Etapas 1-5)

Faça tudo isso ANTES de iniciar o merge ou rebase. Pular a preparação é a causa nº 1 de desastres do tipo "perdi minhas alterações".

1. Certifique-se de que sua árvore de trabalho está limpa

git status

Se algo estiver preparado (staged) ou modificado, comite, armazene (stash) ou descarte. Nunca inicie um merge com uma árvore suja -- os conflitos misturarão seu trabalho em andamento com a resolução do merge e você não conseguirá distingui-los.

# Stash if you want to keep work-in-progress
git stash push -u -m "wip before merging main"

2. Confirme que você está no branch correto

git branch --show-current

Você faz o merge DENTRO do branch atual. Se você está prestes a executar git merge main, você deve estar no seu branch de funcionalidade -- não no main em si.

3. Atualize ambos os branches do remote

git fetch origin
git pull --ff-only origin <your-branch>

Um conflito resolvido contra um main desatualizado é trabalho perdido -- os conflitos reais ainda estão à sua frente. --ff-only recusa-se a fazer merge silenciosamente se seu branch divergiu.

4. Decida: merge ou rebase

Se você não tem certeza, use merge. É mais difícil perder trabalho com um merge.

5. Anote seu commit inicial (sua âncora de segurança)

git rev-parse HEAD
# write this SHA somewhere -- a sticky note, a scratch file, anywhere

Se tudo der errado, git reset --hard <esse-sha> o colocará de volta exatamente onde você começou. git reflog também funciona, mas um SHA anotado é mais rápido sob estresse.

Fase 2: Acionar o Merge (Etapas 6-7)

6. Execute o comando de merge ou rebase

# Merge approach
git merge main
 
# OR rebase approach
git rebase main

Se não houver conflitos, você terminou -- pule para a etapa 19.

7. Leia a saída antes de fazer qualquer outra coisa

O Git imprime exatamente quais arquivos entram em conflito e que tipo de conflito cada um é (conteúdo vs. adição/adição vs. exclusão/modificação). Leia esta lista. Não comece a abrir arquivos até saber quantos conflitos você tem e onde eles estão.

git status
# Look for "Unmerged paths" -- that is your work list

# Get a clean list of just the conflict files
git diff --name-only --diff-filter=U

Fase 3: Entender Cada Conflito (Etapas 8-10)

Resolva os conflitos mais simples primeiro para reduzir a área de superfície. Deixe os mais complicados para o final, quando você tiver ímpeto.

8. Abra o primeiro arquivo em conflito e leia os marcadores

Marcadores de conflito se parecem com isto:

<<<<<<< HEAD
sua versão (o branch para o qual você está fazendo merge)
=======
a versão deles (o branch do qual você está fazendo merge)
>>>>>>> main

Durante um rebase, os rótulos são invertidos: HEAD é o branch base no qual você está fazendo rebase, e o lado >>>>>>> é o seu commit de entrada. Isso pega todos de surpresa pelo menos uma vez.

9. Olhe para ambos os lados em contexto, não apenas para o diff

# Show the full diff with both sides
git diff
 
# Or for one specific file
git diff -- path/to/file.ts
 
# See who wrote each side and why
git log --merge --oneline -- path/to/file.ts
git log -p HEAD..MERGE_HEAD -- path/to/file.ts

Saber por que cada lado fez uma alteração -- não apenas o que mudou -- é a diferença entre uma resolução real e um palpite que compila.

10. Decida a estratégia de resolução para este arquivo

Escolha uma antes de editar:

# Take one side wholesale
git checkout --ours path/to/file.ts
git checkout --theirs path/to/file.ts

Fase 4: Editar e Preparar (Etapas 11-13)

11. Edite o arquivo: remova os marcadores, escreva a resolução

Exclua todas as linhas <<<<<<<, ======= e >>>>>>>. O arquivo deve compilar e ser lido naturalmente como se nunca tivesse entrado em conflito.

Um erro comum é deixar marcadores perdidos em partes não tocadas do arquivo. Procure por eles:

grep -rn '<<<<<<<\|=======\|>>>>>>>' .

12. Execute o arquivo através de suas ferramentas

Para cada arquivo resolvido, execute qualquer verificação que seja rápida e local:

# Type check
npx tsc --noEmit
 
# Format
npx prettier --write path/to/file.ts
 
# Lint
npx eslint path/to/file.ts

Se um Componente de Servidor e um Componente de Cliente importarem um ao outro após o merge, corrija a fronteira agora -- não após a preparação.

13. Prepare o arquivo resolvido

git add path/to/file.ts

Para um rebase, git add NÃO avança automaticamente -- você ainda precisa da etapa 16. Para um merge, preparar todos os conflitos o deixa pronto para commitar.

Repita as etapas 8-13 para cada arquivo em git status.

Fase 5: Verificar (Etapas 14-17)

14. Confirme que não restam conflitos

git status

Todos os arquivos em "Unmerged paths" devem ter desaparecido. Se git diff --name-only --diff-filter=U não retornar nada, você está limpo.

15. Execute a compilação completa e a suíte de testes

npm run build
npm run typecheck
npm test

Um merge que compila arquivos individuais, mas quebra a compilação, é o resultado de merge ruim mais comum. Pegue-o agora, não no CI.

16. Continue o rebase (apenas rebase)

git rebase --continue

Se mais conflitos aparecerem, você agora está resolvendo os conflitos do PRÓXIMO commit. Volte para a etapa 8 para cada um.

17. Verificação de sanidade do diff final

# For a merge: what will the merge commit contain?
git diff HEAD
 
# For a rebase: how does my branch differ from before?
git range-diff <starting-sha>..ORIG_HEAD <starting-sha>..HEAD

Se o diff tiver arquivos que você não tocou ou esperava, algo deu errado. Pare e investigue antes de commitar.

Fase 6: Concluir ou Desistir (Etapas 18-20)

18. Comando de desistência se algo parecer errado

A QUALQUER momento antes do commit final, você pode retornar ao estado da etapa 1:

git merge --abort
git rebase --abort

Se você já comitou e precisa desfazer:

git reset --hard <starting-sha-from-step-5>

Não há vergonha em desistir. Uma nova tentativa limpa é mais rápida do que desembaraçar um merge meio quebrado.

19. Conclua o merge ou rebase

# Merge: commit the merge with the auto-generated message (or write your own)
git commit
 
# Rebase: should already be done after the final --continue

Para um commit de merge, escreva um corpo que explique quais foram os conflitos e como você os resolveu. O seu "eu" futuro agradecerá durante um bisect.

20. Push -- com cuidado

# Merge: regular push is fine
git push
 
# Rebase: force-push, but ONLY to your own branches and ONLY with --force-with-lease
git push --force-with-lease

--force-with-lease recusa o push se outra pessoa comitou no branch remoto desde a última vez que você fez fetch -- é a diferença entre reescrever seu próprio histórico e sobrescrever o commit de um colega. Nunca use --force (sem -with-lease) em um branch compartilhado.

Referência Rápida: Tabela de Desistência

Erros Comuns

• Resolver conflitos em uma base desatualizada. Sempre faça pull do main primeiro (etapa 3). Resolver contra o main da semana passada significa fazer o trabalho duas vezes.
• Misturar seu trabalho em andamento na resolução. Uma árvore suja no início de um merge é um bug garantido. Armazene (stash) primeiro (etapa 1).
• Confundir "ours" e "theirs" durante um rebase. Eles se invertem. Na dúvida, olhe git log para confirmar qual commit é qual.
• Committar com marcadores ainda no arquivo. Sempre use grep para <<<<<<< antes de preparar.
• Fazer force-push de um branch compartilhado. Use --force-with-lease, e nunca no main.