Como resolver um conflito de merge no Git

Um conflito acontece quando o Git tenta juntar duas mudanças e não consegue decidir sozinho qual vale: as duas mexeram nas mesmas linhas de um arquivo, ou uma apagou o que a outra alterou. O Git para no meio do merge, marca os arquivos afetados e espera que você decida. Não é sinal de erro seu; é o que acontece quando duas pessoas trabalham no mesmo trecho.

Num fork, o caso típico é este: você fez uma branch há duas semanas, o projeto original mudou o mesmo parágrafo do README, e agora o GitHub avisa que o pull request tem conflitos. Isso se resolve em duas etapas: trazer o original e decidir cada trecho.

A documentação do GitHub dá a sequência. Ela foi adaptada aqui para a situação de um fork:

1. Entre na pasta do projeto e traga as novidades do original: git fetch upstream.
2. Junte-as na sua branch: git merge upstream/main. O Git avisa dos arquivos em conflito.
3. Rode git status para ver a lista dos arquivos com "unmerged paths".
4. Abra um arquivo em conflito e procure a marca <<<<<<<.
5. Escolha o que fica: a sua versão, a do original ou um texto novo que junte os dois. Apague as três marcas: <<<<<<<, ======= e >>>>>>>.
6. Marque o arquivo como resolvido: git add . (ou git add com o nome do arquivo).
7. Conclua com git commit. A documentação do GitHub sugere uma mensagem do tipo "Resolve merge conflict by incorporating both suggestions".
8. Envie: git push. O pull request se atualiza e o aviso de conflito some.

No arquivo, o trecho em conflito aparece em três partes. Entre <<<<<<< e ======= está a sua versão (a branch em que você está); entre ======= e >>>>>>> está a da outra branch. O texto depois de <<<<<<< e de >>>>>>> indica de onde veio cada lado.

• Não deixe as marcas no arquivo. Se <<<<<<< ficar, ele vai para o commit. Antes do git add, busque as três marcas em cada arquivo.
• Rode os testes depois de resolver: um conflito mal resolvido pode compilar e ainda assim estar errado.
• Em dúvida, pergunte a quem escreveu o outro lado, no próprio pull request.
• Se se perder, git merge --abort desfaz o merge e volta ao estado de antes. Esse comando vem da ajuda do Git, não da página do GitHub que lemos.

Depois de git merge upstream/main, o arquivo README.md aparece assim:

<<<<<<< HEAD
Veja o guia atualizado: https://exemplo.org/novo
=======
Veja o guia completo: https://exemplo.org/guia
>>>>>>> upstream/main

O lado de cima é o texto da branch de Maria; o de baixo, o do original. Ela decide ficar com o endereço do original e com a palavra "atualizado", e deixa uma única linha:

Veja o guia atualizado: https://exemplo.org/guia

Depois roda git add README.md, git commit e git push. O fluxo completo, do fork ao pull request, está no passo a passo, e o hábito que evita a maior parte dos conflitos é manter o fork atualizado.