Sincronizzare una fork con upstream in Git: 3 metodi sicuri

TL;DR: lancia git fetch upstream && git merge upstream/main && git push origin main e la tua fork è aggiornata. È tutto il flusso «sincronizzare una fork con upstream» in una riga — prendi le modifiche dal progetto che hai forkato, poi le spingi sulla tua copia. Se preferisci una storia lineare, sostituisci merge con git rebase upstream/main e forza il push. E se non hai mai collegato il remote upstream, parti dal passaggio 1 qui sotto: quel remote mancante è la causa numero uno di una fork che «non si sincronizza». Tutto il resto — rebase, pulsante Sync di GitHub, branch divergenti non pushabili — è dettaglio sopra questi tre comandi.

Cosa significa sincronizzare una fork con upstream?

Una fork è la tua copia del repository di qualcun altro su GitHub. L’originale è l’upstream; la tua copia è l’origin. Le fork su GitHub non si aggiornano da sole — quando i maintainer mergiano una pull request, la tua copia conserva il codice di ieri. Sincronizzare una fork significa portare i nuovi commit dell’upstream nella tua fork, così il tuo branch coincide — o almeno include — lo stato attuale del progetto.

Conta per due motivi. Primo, i contributi: ogni pull request aperta da una fork stagna porta con sé rumore extra, e i maintainer ti chiederanno di aggiornare prima del merge. Secondo, self-hosting o studio: se esegui una fork in produzione o semplicemente leggi il codice, una fork vecchia di un mese è un mese di bugfix che non hai.

Come si sincronizza una fork con upstream da riga di comando?

Tre passaggi: dichiari l’upstream una volta, scarichi da lui, poi mergi e pushi. Il collegamento è permanente — al prossimo giro i passaggi 2 e 3 bastano.

Passaggio 1 — aggiungi il remote upstream (una volta per clone).

# dentro il tuo clone locale della fork
git remote add upstream https://github.com/ORIGINAL_OWNER/REPO.git
git remote -v   # verifica: origin -> la tua fork, upstream -> l'originale

Trovi l’URL corretto nella pagina del repository originale: il pulsante verde Code. L’errore classico è puntare entrambi i remote alla tua fork — così una «sincronizzazione» non fa in silenzio nulla, perché hai scaricato da una copia tanto ferma quanto la tua.

Passaggio 2 — fetch e merge del branch upstream.

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

Questa è la risposta standard a «git sync fork with upstream command line». Il fast-forward è l’esito normale — la main della tua fork non aveva nulla di nuovo, quindi scivola semplicemente in avanti fino a upstream/main e nessun commit di merge viene creato.

Passaggio 3 — ripeti a richiesta. Non c’è nulla da ricordare oltre a git fetch upstream && git merge upstream/main && git push origin main. Per sapere quanto sei indietro prima di mergiare, lancia git rev-list --count main..upstream/main dopo il fetch.

Meglio rebase o merge quando sincronizzi una fork?

Entrambi fanno atterrare lo stesso codice nella tua fork; differiscono per la storia che lasciano dietro. Scegli una politica per repository e tienila:

Metodo	Comando	Effetto sulla storia	Adatto a
Merge	git merge upstream/main	Commit di merge extra sui branch divergenti	Feature branch con PR aperte — non riscrive mai nulla
Rebase	git rebase upstream/main	I tuoi commit riprodotti sopra, storia lineare	Tenere pulita la main della fork; fork divergenti da riallineare
GitHub UI	Pulsante Sync branch / merge della PR	Come il merge	Recupero rapido senza clone aperto

La variante con rebase della sincronizzazione:

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

Il force push è obbligatorio perché il rebase riscrive gli ID dei commit — il branch remoto della tua fork non discende più da quello locale. Preferisci sempre --force-with-lease a --force: rifiuta di sovrascrivere il remote se nel frattempo ha pushato qualcun altro (o un’altra tua macchina), il che rende sicuro per impostazione predefinita il comando pericoloso.

Una regola da tatuarsi sul polso: mai fare rebase di un branch con una pull request aperta, a meno che tu non sappia cosa stai facendo — il rebase cambia gli ID dei commit e può staccare una PR aperta dai suoi commit. Sincronizza la main con il merge (o fai rebase prima di iniziare lavoro nuovo) e tieni i branch delle PR fuori da tutto ciò.

Perché la mia fork non si sincronizza con upstream?

I quattro soliti sospetti, nell’ordine in cui compaiono nei terminal veri:

1. Nessun remote upstream — git remote -v mostra solo origin. Sintomo: git fetch upstream fallisce con 'upstream' does not appear to be a git repository. Fix: passaggio 1 qui sopra.
2. Hai fatto fetch ma mai merge — il fetch aggiorna upstream/main nel repository locale ma non tocca alcun branch di lavoro. Sintomo: git log sembra vecchio dopo un fetch riuscito. Fix: git merge upstream/main.
3. Storia divergente — hai committato sulla main della tua fork, e l’upstream nel frattempo è avanzato. git pull allora si lamenta di storie non correlate o forza un merge. Fix, se vuoi che vinca l’upstream: git reset --hard upstream/main (butta via i tuoi commit presenti solo sulla main locale — controlla git stash list o fai prima un backup su un branch; se il reset sbagliato è già avvenuto, la via di recupero è la stessa di git undo last commit: git reflog conosce ancora la vecchia punta).
4. Push rifiutato come non-fast-forward dopo un rebase — hai rebasato ma hai pushato normalmente. Fix: git push --force-with-lease origin main.

Quinto caso, più raro: il repository upstream è stato rinominato o cancellato, così anche l’URL del passaggio 1 dà 404. GitHub reindirizza i repository rinominati, quindi un fallimento netto di solito significa cancellato o reso privato — niente con cui sincronizzarsi.

Si può sincronizzare una fork dal sito di GitHub?

Sì. Nella pagina della tua fork, il selettore dei branch mostra un pulsante Sync fork ogni volta che il tuo branch è indietro; un clic porta dentro l’upstream. Più in basso, la stessa cosa funziona come pull request: apri una PR da upstream/main verso la main della tua fork e mergiala.

I limiti del pulsante spiegano quando tornare alla CLI: esegue solo fast-forward o merge — non fa rebase, e si rifiuta del tutto quando i branch sono divergenti, suggerendoti di scartare i commit o di usare la riga di comando. Inoltre sincronizza solo il branch predefinito. Per tutto ciò che va oltre un semplice recupero, i tre comandi qui sopra sono lo strumento.

Ogni quanto sincronizzare la propria fork?

Prima di ogni pezzo di lavoro nuovo è la risposta onesta: parti in branch da una main fresca, e nessuna PR che apri comincia con «questo si basa su una versione di tre settimane fa». Per le fork a cui contribuisci attivamente, una sincronizzazione giornaliera o per sessione della main costa secondi. Per una fork che solo leggi o deployi, sincronizza quando l’upstream pubblica qualcosa che vuoi — iscriviti al feed delle release del repository originale e sincronizza a ogni release. Sincronizzare costa poco proprio perché è routine; una fork con sei mesi di ritardo spesso richiede chirurgia invece di un merge, ed è così che «sincronizzo la mia fork» diventa un pomeriggio.

Cheat sheet

# configurazione una tantum
git remote add upstream https://github.com/ORIGINAL_OWNER/REPO.git

# sincronizzazione di routine (politica merge)
git fetch upstream && git merge upstream/main && git push origin main

# sincronizzazione di routine (politica rebase, storia lineare)
git fetch upstream && git rebase upstream/main && git push --force-with-lease origin main

# quanto sono indietro?
git fetch upstream && git rev-list --count main..upstream/main

# divergenza irrecuperabile — main identica a upstream (distruttivo)
git fetch upstream && git reset --hard upstream/main && git push --force-with-lease origin main

Tieni il due-righe di routine nella memoria muscolare e la fork divergente resta una curiosità da leggere, non un problema da sistemare. Se le tue pulizie git si estendono ai server, il journalctl cheat sheet copre l’altra metà di come tenere leggibile la storia di una macchina.