git clone: come clonare un repository da GitHub e non solo

Il comando git clone crea una copia locale completa di un repository remoto: file, tutta la storia dei commit, branch e tag. È il modo standard per iniziare a lavorare su un progetto che si trova già su GitHub, GitLab o un server aziendale. A differenza del download di un archivio ZIP, il clone è un repository a tutti gli effetti, in cui si può fare commit e inviare le modifiche indietro.

Uso base di git clone

Copiate l'indirizzo del repository (su GitHub è il pulsante verde «Code») ed eseguite:

git clone https://github.com/username/project.git

Cloning into 'project'...
remote: Enumerating objects: 1532, done.
remote: Counting objects: 100% (1532/1532), done.
remote: Compressing objects: 100% (812/812), done.
Receiving objects: 100% (1532/1532), 2.41 MiB | 6.10 MiB/s, done.
Resolving deltas: 100% (701/701), done.

Git crea la cartella project nella directory corrente (il nome viene preso dall'indirizzo senza .git). Poi entrateci:

cd project
git status

Cosa fa git clone dietro le quinte

Clonare non significa solo scaricare file. Capire questi passaggi spiega perché dopo il clone tutto «funziona e basta» e da dove arrivano i branch con il prefisso origin/. Passo per passo, il comando:

1. crea la cartella ed esegue al suo interno l'equivalente di git init;
2. aggiunge un remote chiamato origin che punta all'indirizzo di origine;
3. scarica tutti gli oggetti e i riferimenti, l'equivalente di git fetch;
4. crea i branch remoti origin/main, origin/develop e così via;
5. crea il branch locale predefinito (di solito main), lo collega a origin/main ed estrae i file.

Per questo dopo il clone non serve configurare a mano git remote: git push e git pull funzionano subito.

git remote -v
origin  https://github.com/username/project.git (fetch)
origin  https://github.com/username/project.git (push)

Clonare via HTTPS e via SSH

Per leggere progetti open source altrui basta HTTPS. Per i vostri repository, su cui fate push regolarmente, è più comodo SSH:

git clone git@github.com:username/project.git

Se avete già clonato via HTTPS e volete passare a SSH, non serve riscaricare nulla:

git remote set-url origin git@github.com:username/project.git

Come clonare in una cartella specifica

Il secondo argomento è il nome o il percorso della directory di destinazione:

# In una cartella con un nome diverso
git clone https://github.com/username/project.git my-copy

# Nella cartella corrente (deve essere vuota)
git clone https://github.com/username/project.git .

Se la cartella di destinazione esiste e non è vuota, Git rifiuta: fatal: destination path 'project' already exists and is not an empty directory.

Come clonare un branch specifico

Di default dopo il clone vi trovate sul branch predefinito del repository remoto. Per finire subito su un altro, usate -b (--branch):

git clone -b develop https://github.com/username/project.git

Attenzione: in questo modo vengono scaricati tutti i branch, semplicemente vi ritroverete su develop. Se vi serve un solo branch senza gli altri, aggiungete --single-branch:

git clone -b develop --single-branch https://github.com/username/project.git

L'opzione -b accetta anche il nome di un tag: otterrete lo stato del progetto al momento della release (in modalità detached HEAD):

git clone -b v2.1.0 --depth 1 https://github.com/username/project.git

Dove sono gli altri branch dopo il clone

Chi inizia si stupisce: git branch mostra solo main. Gli altri branch sono scaricati come remoti e si vedono così:

git branch -a

* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/develop
  remotes/origin/feature/login

Per iniziare a lavorare su uno di essi basta spostarsi usando il nome breve: Git crea da solo un branch locale che traccia quello remoto:

git switch develop

Clone superficiale: --depth per i repository grandi

Nei progetti di lunga data la storia può pesare gigabyte. Se vi serve solo il codice attuale, ad esempio nella CI o solo per compilare il progetto, scaricate gli ultimi commit:

git clone --depth 1 https://github.com/username/big-project.git

L'opzione --depth implica --single-branch, quindi arrivano solo il branch predefinito e un commit. Se più avanti vi servirà la storia completa, potete scaricarla:

git fetch --unshallow

Si può indicare anche un'altra profondità, ad esempio --depth 50, o limitare la storia per data con --shallow-since=2025-01-01. Per lo sviluppo attivo il clone superficiale è scomodo: git log, git blame e la ricerca nella storia saranno incompleti.

Clone parziale: --filter

Un'alternativa per monorepo enormi è scaricare la storia dei commit e caricare il contenuto dei file su richiesta:

git clone --filter=blob:none https://github.com/username/monorepo.git

Così conservate la storia completa per log e per il cambio di branch, ma risparmiate traffico e spazio. Richiede il supporto del server; GitHub e GitLab lo offrono.

Clone mirror e migrazione di un repository

Un clone normale prende i branch come remoti e non copia i riferimenti di servizio del server. Per spostare un progetto su un altro hosting o creare una copia di backup identica si usa --mirror:

git clone --mirror https://github.com/username/project.git
cd project.git
git push --mirror git@gitlab.com:username/project.git

Il mirror è un repository bare senza file di lavoro, in cui tutti i branch e i tag sono conservati come locali. Il comando git push --mirror li invia al nuovo server per intero, e la storia viene trasferita senza perdite. Tenete presente che issue, pull request e impostazioni dell'hosting non vengono trasferite così: sono dati del servizio, non di Git.

L'opzione simile --bare crea anch'essa un repository senza working directory, ma copia solo branch e tag. È adatta per creare un repository centrale sul proprio server a partire da un progetto esistente.

Clonare con i submodule

Se il progetto usa i git submodule, di default le loro cartelle risulteranno vuote. Per scaricare tutto subito:

git clone --recurse-submodules https://github.com/username/project.git

Se avete già clonato senza l'opzione, scaricate i submodule:

git submodule update --init --recursive

git clone, fork e download dello ZIP

Fork e clone non sono in competizione: nell'open source prima si fa il fork sul sito, poi si clona il proprio fork e si aggiunge l'originale come secondo remote:

git clone git@github.com:me/project.git
cd project
git remote add upstream https://github.com/author/project.git
git fetch upstream

Errori frequenti di git clone

«Repository not found»

Un refuso nell'indirizzo, oppure il repository è privato e non avete accesso. Per i repository privati GitHub risponde di proposito «not found» e non «accesso negato». Controllate l'indirizzo e di essere autenticati con l'account giusto.

«Permission denied (publickey)»

Clone via SSH, ma la chiave non è configurata. Verificate con ssh -T git@github.com, aggiungete la chiave pubblica nelle impostazioni dell'account o clonate temporaneamente via HTTPS.

«Authentication failed» via HTTPS

Avete inserito la password dell'account. GitHub da tempo richiede un Personal Access Token al posto della password per le operazioni Git via HTTPS. Se Git ha memorizzato credenziali sbagliate, eliminatele dal gestore delle credenziali del sistema.

Interruzione su un repository grande

Errori come early EOF o RPC failed sono spesso legati a una rete instabile e alle dimensioni. Aiuta un clone superficiale --depth 1 seguito da git fetch --unshallow, oppure un clone via SSH.

Problemi con i fine riga su Windows

Dopo il clone tutti i file risultano «modificati»: è l'effetto della conversione CRLF/LF. Impostate git config --global core.autocrlf true su Windows (o input su Linux e macOS) e, meglio ancora, definite le regole nel .gitattributes del progetto.

Cosa fare subito dopo il clone

Il clone è pronto, ma prima di modificare il codice conviene dedicare un paio di minuti alla preparazione. Vi eviterà i problemi tipici del primo giorno su un progetto altrui.

1. Leggete README e CONTRIBUTING. Di solito spiegano come installare le dipendenze, lanciare i test e come si chiamano i branch nel progetto.
2. Controllate branch e stato. git status e git log --oneline -5 mostrano dove siete e quali sono le ultime modifiche.
3. Create un vostro branch. Non lavorate direttamente su main: git switch -c feature/my-task.
4. Verificate l'autore dei commit. Se sul computer avete più account (personale e di lavoro), impostate l'e-mail per il singolo repository senza --global: git config user.email "you@company.com".
5. Installate le dipendenze. Cartelle come node_modules o venv non si mettono nel repository, si creano in locale: npm install, pip install -r requirements.txt e così via.

Come tenere aggiornato il clone

Il clone si fa una volta sola. Dopo, i nuovi commit dei colleghi si scaricano dallo stesso origin:

# Vedere cosa è arrivato sul server senza modificare nulla
git fetch
git log --oneline main..origin/main

# Integrare le modifiche nel branch corrente
git pull

L'abitudine di fare prima git fetch e guardare cosa è arrivato evita conflitti a sorpresa. Non serve clonare di nuovo il progetto «per aggiornarlo»: così si perdono i branch locali e il lavoro non committato.

Promemoria su git clone

In sintesi

git clone scarica l'intero repository e configura subito il collegamento con il server tramite origin, quindi dopo si può fare commit, push e pull senza altre configurazioni. Per i vostri progetti usate SSH, per quelli grandi --depth o --filter, per un branch specifico -b. Il lavoro con i repository remoti, push, pull e fetch sono trattati in pratica nel corso su Git.