Forking workflow

Panoramica

Il forking workflow è il modello standard per i progetti open source e per qualsiasi contesto in cui i collaboratori non dispongono di accesso diretto in scrittura al repository principale. Invece di effettuare push su un repository condiviso, ogni collaboratore lavora nella propria copia lato server — un fork — e propone le modifiche tramite una pull request. È il modo in cui milioni di contributi raggiungono ogni giorno i progetti su GitHub e GitLab.

Questa pagina spiega cos'è un fork, in cosa differisce dal workflow con repository condiviso, i comandi precisi per clonare, configurare i remote, fare push e aprire una pull request, e — soprattutto — come mantenere il tuo fork sincronizzato in modo che i tuoi contributi siano facili da unire.

La differenza fondamentale

Nel feature branch workflow, tutti effettuano push dei branch su un unico repository condiviso. Il forking workflow aggiunge un livello: esistono ora due repository lato server — il repo upstream ufficiale, su cui non puoi scrivere, e il tuo fork, che controlli completamente. Esegui il push sul tuo fork e chiedi all'upstream di fare il pull da esso.

Questo è talvolta chiamato workflow triangolare per via del modo in cui si relazionano le tre copie:

        upstream (official repo, read-only to you)
          ▲   │
   pull   │   │ fork (one click, server-side)
  request │   ▼
        your fork (origin) ──clone──▶ your laptop
                            ◀──push──

Esegui il fetch da upstream, il push verso origin (il tuo fork), e la pull request è il ponte che chiede a un maintainer di fare il pull del tuo branch dal tuo fork verso upstream.

Passo per passo

1. Fork del repository upstream sulla piattaforma di hosting. Questo crea your-fork sotto il tuo account — una copia completa lato server.

2. Clone del tuo fork sul tuo computer:

git clone https://github.com/you/project.git
cd project

3. Aggiungi upstream come remote in modo da poter scaricare le ultime modifiche del progetto:

git remote add upstream https://github.com/original/project.git

Il tuo clone ora ha due remote. Verificali con git remote -v:

origin    https://github.com/you/project.git (fetch)
origin    https://github.com/you/project.git (push)
upstream  https://github.com/original/project.git (fetch)
upstream  https://github.com/original/project.git (push)

origin punta al tuo fork (dove effettui il push); upstream punta al repo ufficiale (da cui esegui il fetch). Consulta git remote per gestire questi remote.

4. Crea un branch e lavora. Crea sempre il branch da un main aggiornato — non eseguire mai commit direttamente sul main del tuo fork, in modo che rimanga uno specchio pulito dell'upstream:

git switch -c fix/typo-in-docs
# ...make changes and commit...
git push -u origin fix/typo-in-docs

Il flag -u (--set-upstream) collega il tuo branch locale a quello sul tuo fork, così in seguito potrai semplicemente eseguire git push.

5. Apri una pull request dal branch del tuo fork verso il branch main dell'upstream. Nell'interfaccia web è un pulsante; con la CLI di GitHub puoi farlo dal terminale:

gh pr create --base main --head you:fix/typo-in-docs

I maintainer la revisionano, richiedono modifiche se necessario, e la uniscono quando sono soddisfatti. Se chiedono modifiche, esegui il commit e git push di nuovo — la pull request aperta si aggiorna automaticamente.

Mantenere il fork sincronizzato con upstream

Il progetto continua ad evolversi mentre lavori, quindi aggiorna il tuo fork dall'upstream prima di iniziare nuovi branch. Usa git fetch per scaricare i commit di upstream, poi uniscili con git merge (o rebase):

git switch main
git fetch upstream
git merge upstream/main      # fast-forward main onto upstream
git push origin main         # update your fork's main on the server

Poiché non esegui mai commit direttamente su main, questo merge è sempre un clean fast-forward — nessun conflitto. Puoi imporlo con git merge --ff-only upstream/main, che fallisce in modo esplicito se main si è discostato.

Aggiornare un feature branch in corso

Se il tuo branch rimane indietro mentre una revisione si prolunga, porta i nuovi commit di upstream al suo interno. Il rebase mantiene una cronologia lineare che i maintainer di solito preferiscono:

git fetch upstream
git switch fix/typo-in-docs
git rebase upstream/main
git push --force-with-lease    # rewrite your fork's branch safely

--force-with-lease rifiuta di sovrascrivere il remote se qualcun altro ha effettuato push nel frattempo, il che lo rende molto più sicuro di un semplice --force. Se preferisci evitare di riscrivere la cronologia, esegui invece git merge upstream/main. Consulta git rebase e merge conflicts per gestire i dettagli.

Perché funziona

Il modello di forking consente a un progetto di accettare contributi da chiunque mantenendo il repository ufficiale protetto — solo i maintainer possono eseguire merge. I collaboratori non necessitano di permessi speciali, la revisione avviene in modo trasparente su ogni pull request, e la cronologia dell'upstream rimane pulita. Per la collaborazione su larga scala con utenti non fidati, è il più sicuro tra i workflow Git comuni.

Usalo quando i collaboratori non dispongono di accesso in scrittura (la maggior parte dell'open source). Quando tutti fanno parte dello stesso team e sono fidati, il più semplice feature branch workflow o Gitflow evita il fork aggiuntivo. Confrontali fianco a fianco in Git workflows.

Esercitazione