Como atualizar um fork no GitHub com o upstream

Quando você faz um fork, recebe uma foto do projeto naquele dia. O original continua recebendo commits de outras pessoas, e o seu fork não os recebe sozinho. Se você começar uma branch nova em cima de uma main antiga, o pull request pode nascer com conflitos ou repetir trabalho que já foi feito. Por isso o hábito é sincronizar antes de cada nova contribuição.

A documentação do GitHub descreve três jeitos de sincronizar: pelo botão no site, pelo GitHub CLI e pela linha de comando com Git.

Na página principal do seu fork, acima da lista de arquivos, abra o menu Sync fork, confira as novidades do original e clique em Update branch. Se houver conflito, o GitHub propõe criar um pull request para resolvê-lo. Esse botão atualiza o fork no GitHub; o seu computador continua como estava até você baixar a novidade com git pull.

O comando é gh repo sync com o seu fork e a branch, por exemplo gh repo sync maria-dev/listaki -b main. A documentação avisa que a opção --force sobrescreve a branch de destino quando há conflito, então só a use se tiver certeza de que não perde nada seu.

Com o upstream configurado (veja o guia de como fazer o fork), a documentação mostra três comandos. Eles foram executados aqui, em dois repositórios locais de exemplo:

git fetch upstream
git switch main
git merge upstream/main
git push origin main

• git fetch upstream baixa as novidades do original, sem mexer nos seus arquivos.
• git switch main volta para a main. A documentação usa git checkout main; desde o Git 2.23, git switch faz o mesmo para trocar de branch.
• git merge upstream/main junta as novidades na sua main local.
• git push origin main envia a main atualizada para o seu fork. A página do GitHub lembra que o merge só atualiza a cópia local: para atualizar o fork no site, é preciso enviar.

• fatal: 'upstream' does not appear to be a git repository: você não registrou o original. Rode git remote add upstream <endereço do original>.
• error: Your local changes to the following files would be overwritten by merge:: há alterações suas, não guardadas, em arquivos que o merge também muda. Guarde-as num commit (ou com git stash) e repita.
• ! [rejected] main -> main (fetch first): o fork recebeu commits que a sua main local não tem, por exemplo pelo botão Sync fork. Rode git fetch origin, junte com git merge origin/main, confira e envie de novo.

Maria teve o primeiro pull request aceito. Duas semanas depois quer corrigir outro detalhe. Antes de criar a branch, ela roda git switch main, git fetch upstream, git merge upstream/main e git push origin main. O Git responde Fast-forward: sem conflito, a main dela passa a ser igual à do original. Só então ela cria a branch com git switch -c corrige-exemplo.

Se o merge não fosse um avanço simples, o Git abriria um conflito; o guia de como resolver um conflito de merge mostra o que fazer.