Sincronizar fork com upstream no Git: 3 métodos seguros

TL;DR: rode git fetch upstream && git merge upstream/main && git push origin main e seu fork está atualizado. Esse é o fluxo completo de “git sync fork with upstream” em uma linha — puxe as mudanças do projeto que você forkou e envie para a sua cópia. Se você prefere histórico linear, troque o merge por git rebase upstream/main e faça force-push. E se você nunca conectou o remote upstream, comece pelo passo 1 abaixo, porque esse remote ausente é a razão número um de um fork “não sincronizar”. Todo o resto — rebase, botão de sync do GitHub, branches divergidas que não sobem — é detalhe por cima desses três comandos.

O que significa sincronizar um fork com o upstream?

Um fork é a sua cópia do repositório de outra pessoa no GitHub. O original é o upstream; a sua cópia é o origin. Forks do GitHub não se atualizam sozinhos — quando os mantenedores fazem merge de um pull request, sua cópia continua com o código de ontem. Sincronizar um fork significa trazer os commits novos do upstream para dentro do seu fork, para que sua branch iguale — ou ao menos contenha — o estado atual do projeto.

Isso importa por dois motivos. Primeiro, contribuições: todo pull request aberto de um fork desatualizado carrega ruído extra, e os mantenedores vão pedir que você atualize antes do merge. Segundo, self-hosting ou estudo: se você roda um fork em produção ou só lê o código, um fork com um mês de atraso é um mês de correções de bug que você não tem.

Como sincronizar um fork com o upstream pela linha de comando?

Três passos: declare o upstream uma vez, faça fetch dele, depois merge e push. A conexão é permanente — da próxima vez, só os passos 2 e 3.

Passo 1 — adicione o remote upstream (uma vez por clone).

# dentro do seu clone local do fork
git remote add upstream https://github.com/ORIGINAL_OWNER/REPO.git
git remote -v   # confirme: origin -> seu fork, upstream -> o original

A URL correta fica na página do repositório original: o botão verde Code. Um erro comum é apontar os dois remotes para o seu fork — aí o “sync” silenciosamente não faz nada, porque você puxou de uma cópia tão desatualizada quanto a sua.

Passo 2 — faça fetch e merge da branch do upstream.

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

Essa é a resposta padrão para “git sync fork com upstream na linha de comando”. Um fast-forward é o desfecho normal — a main do seu fork não tinha nada de novo, então ela simplesmente desliza até a upstream/main e nenhum commit de merge é criado.

Passo 3 — repita quando precisar. Não há nada a decorar além de git fetch upstream && git merge upstream/main && git push origin main. Para ver o quanto você está atrás antes do merge, rode git rev-list --count main..upstream/main depois do fetch.

Melhor rebase ou merge ao sincronizar um fork?

Os dois trazem o mesmo código para o seu fork; diferem no histórico que deixam para trás. Escolha uma política por repositório e mantenha-a:

Método	Comando	Resultado no histórico	Melhor para
Merge	git merge upstream/main	Commit de merge extra em branches divergidas	Feature branches com PR aberto — nunca reescreve nada
Rebase	git rebase upstream/main	Seus commits reaplicados no topo, histórico linear	Manter a main do fork limpa; forks divergidos que você quer resetar
Interface do GitHub	Botão Sync branch / merge de PR	Igual ao merge	Atualização rápida sem clone aberto

A variante com rebase do sync:

git fetch upstream
git rebase upstream/main
git push --force-with-lease origin main

O force-push é obrigatório porque o rebase reescreve os IDs dos commits — a branch remota do seu fork não desce mais da sua local. Prefira sempre --force-with-lease a --force: ele recusa sobrescrever o remote se alguém (ou outra máquina sua) fez push nesse meio-tempo, o que torna o comando perigoso seguro por padrão.

Uma regra que vale tatuagem: nunca faça rebase de uma branch com pull request aberto, a menos que saiba o que está fazendo — o rebase muda os IDs dos commits, o que pode desvincular um PR aberto dos seus commits. Sincronize a main com merge (ou faça rebase dela antes de começar trabalho novo) e mantenha as branches de PR fora disso.

Por que meu fork não sincroniza com o upstream?

Os quatro suspeitos de sempre, na ordem em que aparecem em terminais reais:

1. Remote upstream ausente — o git remote -v mostra só o origin. Sintoma: git fetch upstream falha com 'upstream' does not appear to be a git repository. Conserto: passo 1 acima.
2. Você fez fetch mas nunca merge — o fetch atualiza a upstream/main no seu repositório local mas não toca em nenhuma branch de trabalho. Sintoma: o git log continua velho depois de um fetch bem-sucedido. Conserto: git merge upstream/main.
3. Histórico divergido — você commitou na main do seu fork, e o upstream andou também. O git pull reclama de históricos não relacionados ou força um merge. Conserto, se você quer que o upstream vença: git reset --hard upstream/main (joga fora seus commits que só existiam na sua main — confira o git stash list ou faça backup numa branch antes; se o reset ruim já aconteceu, o caminho de recuperação é o mesmo do desfazer o último commit: o git reflog ainda sabe onde ficava a ponta antiga).
4. Push rejeitado como non-fast-forward depois de um rebase — você fez rebase mas deu push normal. Conserto: git push --force-with-lease origin main.

Um quinto caso, raro: o repositório upstream foi renomeado ou apagado, e até a URL do passo 1 dá 404. O GitHub redireciona repositórios renomeados, então uma falha dura geralmente significa apagado ou tornado privado — não há para onde sincronizar.

Dá para sincronizar o fork pelo site do GitHub?

Sim. Na página do seu fork, o seletor de branch mostra um botão Sync fork sempre que sua branch está atrás; um clique traz o upstream para dentro. Abaixo da dobra, o mesmo efeito funciona como pull request: abra um PR da upstream/main para a main do seu fork e faça o merge.

Os limites do botão explicam quando voltar para a CLI: ele só faz fast-forward ou merge — não faz rebase, e simplesmente recusa quando as branches divergiram, mandando você descartar commits ou usar a linha de comando. Ele também sincroniza só a branch padrão. Para tudo que passa de uma atualização simples, os três comandos acima são a ferramenta.

Com que frequência sincronizar o fork?

Antes de cada trabalho novo é a resposta honesta: crie a branch a partir de uma main fresca, e nenhum PR seu começa com “isso se baseia numa versão de três semanas atrás”. Para forks em que você contribui ativamente, um sync diário ou por sessão da main custa segundos. Para um fork que você só lê ou faz deploy, sincronize quando o upstream lançar algo que você quer — assine o feed de releases do repositório original e sincronize a cada release. Sincronizar é barato justamente porque é rotina; um fork com seis meses de atraso frequentemente precisa de cirurgia em vez de merge, e é assim que “sincronizar meu fork” vira uma tarde inteira.

Cola rápida

# configuração única
git remote add upstream https://github.com/ORIGINAL_OWNER/REPO.git

# sync de rotina (política de merge)
git fetch upstream && git merge upstream/main && git push origin main

# sync de rotina (política de rebase, histórico linear)
git fetch upstream && git rebase upstream/main && git push --force-with-lease origin main

# quantos commits atrás estou?
git fetch upstream && git rev-list --count main..upstream/main

# divergência sem conserto — tornar a main idêntica ao upstream (destrutivo)
git fetch upstream && git reset --hard upstream/main && git push --force-with-lease origin main

Guarde o combo de rotina na memória muscular e o fork divergido segue sendo uma curiosidade que você lê sobre, não um problema que você conserta. Se a sua arrumação de Git se estende a servidores, o cheat sheet de journalctl cobre a outra metade de manter o histórico de uma máquina legível.