Remote, origin, upstream: dove vivono i remoti

Un remote è un nome locale che punta all’URL di un altro repository. Non è il repository remoto in sé: è una voce di configurazione nel tuo clone.

origin non è speciale per magia. È solo il nome che Git assegna di default al repository da cui hai clonato. In un fork, origin spesso è il tuo fork, mentre upstream è il progetto originale.

Perché questa lezione conta

Molti problemi di collaborazione nascono da confusione sui remoti: push sul fork sbagliato, pull dal repository sbagliato, branch locali che inseguono branch remoti non attesi.

Capire i remote significa sapere da dove scarichi, dove pubblichi e quale repository consideri fonte autorevole.

Obiettivo operativo

Alla fine della lezione devi saper leggere, aggiungere, rinominare e rimuovere remote; distinguere origin e upstream; scegliere SSH o HTTPS in modo consapevole.

Vedere i remoti

git remote -v

Output tipico:

origin  git@github.com:tu/progetto.git (fetch)
origin  git@github.com:tu/progetto.git (push)

Fetch e push possono avere URL diversi, anche se di solito coincidono. Questa distinzione è utile in contesti avanzati, ma per la maggior parte dei progetti deve essere semplice e prevedibile.

Aggiungere upstream

Nel workflow fork-based:

git remote add upstream git@github.com:org/progetto.git
git fetch upstream

Da quel momento hai:

origin   -> tuo fork
upstream -> repo originale

Tu pushi su origin, apri PR verso upstream.

Remote-tracking branch

Quando fai fetch, Git aggiorna riferimenti come:

origin/main
upstream/main

Non sono branch locali su cui lavori direttamente. Sono il tuo ultimo snapshot conosciuto dello stato remoto.

Puoi vedere:

git branch -r
git log --oneline --decorate --all --graph

Fonte autorevole

In ogni repo collaborativo deve essere chiaro quale remote è la fonte autorevole. Nei progetti aziendali di solito è origin. Nei fork è spesso upstream. Nei mirror o nei deploy automatici possono esistere remote di sola lettura o remote dedicati alla pubblicazione.

Annota questa scelta nel README o nella documentazione interna. Quando il team non sa quale remote comanda, nascono branch duplicati, PR contro target sbagliati e fix applicati nel posto meno utile.

HTTPS vs SSH

HTTPS. Semplice da configurare, spesso usa token o credential manager. Buono in ambienti dove SSH è bloccato.

SSH. Comodo per uso quotidiano, usa chiavi, non richiede token a ogni operazione. Richiede setup corretto di chiave e agent.

Controllo SSH:

ssh -T git@github.com

Non mettere token o password negli URL remoti.

Modificare un remote

git remote set-url origin git@github.com:tu/nuovo.git
git remote rename origin fork
git remote remove upstream

Dopo ogni modifica:

git remote -v
git fetch --all --prune

Laboratorio guidato

Scegli un repo reale o demo:

1. stampa git remote -v;
2. identifica quale remote riceve push;
3. aggiungi un secondo remote fittizio o reale;
4. fai fetch da entrambi;
5. osserva git branch -r;
6. disegna relazione tra locale, origin e upstream.

Output atteso

Una checklist setup remote:

remote name:
URL fetch:
URL push:
protocollo:
credenziali:
branch principale:
chi è fonte autorevole:

Errori comuni

Pensare che origin sia sempre il repo principale. In un fork spesso è il tuo fork.

Pushare sul remote sbagliato. Controlla git remote -v prima di operazioni delicate.

Confondere origin/main con main. Il primo è tracking remoto, il secondo è branch locale.

Salvare credenziali negli URL. Usa credential manager, token sicuri o SSH.

Checklist di verifica

• so leggere git remote -v;
• so aggiungere upstream;
• so distinguere branch locali e remote-tracking branch;
• so cambiare URL di un remote;
• so spiegare dove fa push il mio branch.

Collegamenti

• Modulo: Collaborazione con remoti — lezione 21 del corso.
• La prossima lezione distingue fetch e pull.