Cloni superficiali in Git: quando e come usarli

I cloni superficiali in Git recuperano solo una parte della cronologia dei commit. Sono utili quando un lavoro CI, un passaggio di distribuzione o un'ispezione rapida necessitano del codice corrente ma non di anni di cronologia.

Non sono la scelta predefinita migliore per ogni workstation di sviluppo. Un clone superficiale può risparmiare tempo e spazio su disco, ma limita anche i comandi basati sulla cronologia finché non recuperi più commit.

Cos'è un clone superficiale?

Un clone standard recupera abbastanza cronologia per il normale lavoro sui rami, l'ispezione della cronologia, il checkout di tag vecchi e l'indagine offline. Un clone superficiale tronca quella cronologia a una profondità che scegli.

Ad esempio, --depth 1 recupera il commit più recente per il ramo selezionato. --depth 50 recupera più cronologia recente, ma ancora non l'intera discendenza.

Vantaggi dell'uso dei cloni superficiali

Il vantaggio principale è un costo di trasferimento inferiore:

• Checkout iniziale più veloce per repository grandi.
• Minor utilizzo del disco su agenti di build di breve durata.
• Minor larghezza di banda su reti lente o a consumo.
• Meno cronologia da elaborare per Git durante il clone iniziale.

In una pipeline CI che costruisce il commit corrente e butta via l'area di lavoro, un clone superficiale è spesso un guadagno netto.

Svantaggi e limitazioni dei cloni superficiali

Il compromesso è la cronologia mancante:

• git log si ferma al confine superficiale.
• git blame potrebbe non essere in grado di seguire modifiche più vecchie.
• Tag o commit vecchi potrebbero non essere disponibili finché non vengono recuperati.
• Rebasing e merge possono essere più difficili se Git ha bisogno di una base di merge mancante.
• Alcuni flussi di lavoro di rilascio o audit si aspettano una cronologia completa.

Se il tuo lavoro spesso implica il debug di regressioni vecchie, la preparazione di rilasci o il backport di modifiche, inizia con un clone completo.

Come creare un clone superficiale

Usa git clone --depth:

git clone --depth <numero> <url_repository>

Ad esempio, per clonare un repository e recuperare solo gli ultimi 10 commit:

git clone --depth 10 https://github.com/esempio/repo-grande.git

Per un lavoro di build che necessita solo del ramo più recente:

git clone --depth 1 https://github.com/esempio/progetto.git

Per clonare un ramo specifico:

git clone --depth 1 -b develop https://github.com/esempio/progetto.git

Puoi anche aggiungere --single-branch quando vuoi solo la cronologia per quel ramo:

git clone --depth 1 --single-branch --branch develop https://github.com/esempio/progetto.git

Gestione dei cloni superficiali

Recuperare più cronologia (approfondire il clone)

Se hai bisogno di più cronologia dopo il clone, approfondisci il repository:

git fetch --deepen=50 origin

Questo recupera 50 commit in più oltre l'attuale confine superficiale.

Puoi anche impostare la profondità totale desiderata:

git fetch --depth=100 origin

Il punto importante: git remote set-depth non è un comando Git valido. La profondità è controllata tramite le opzioni di clone e fetch.

Recuperare i tag

I cloni superficiali potrebbero non includere tutti i tag, specialmente quelli che puntano a commit più vecchi. Recupera i tag solo se il tuo flusso di lavoro ne ha bisogno:

git fetch --tags origin

Rimuovere la superficialità di un repository

Per convertire un clone superficiale in un clone completo, recupera il resto della cronologia:

git fetch --unshallow origin

Questo comando scaricherà la cronologia rimanente dal repository remoto.

Push da un clone superficiale

Il push da un clone superficiale può funzionare quando i tuoi nuovi commit sono basati sul ramo remoto più recente che hai recuperato. È comunque una scelta poco adatta per uno sviluppo a lungo termine perché la cronologia mancante può rendere più difficili rebase, risoluzione dei conflitti e revisione.

Se incontri problemi di push o merge legati alla cronologia, recupera più cronologia o rimuovi la superficialità del clone prima di continuare.

Quando usare i cloni superficiali

Usali quando il lavoro è di breve durata e la cronologia non è importante:

• Checkout CI/CD.
• Ispezione in sola lettura.
• Ambienti di riproduzione temporanei.
• Build di documentazione.
• Repository grandi su reti lente.

Quando non usare i cloni superficiali

Evitali quando hai regolarmente bisogno di:

• git log, git blame o git bisect approfonditi.
• Lavoro di rilascio che utilizza tag vecchi.
• Lavoro complesso di merge o rebase.
• Debug offline attraverso la cronologia.
• Flussi di lavoro di contribuzione che si aspettano un clone completo.

Conclusione pratica

Usa git clone --depth 1 per lavori usa e getta che necessitano solo del codice più recente. Usa un clone completo per lo sviluppo normale a meno che tu non abbia una chiara ragione per non farlo.

Se un clone superficiale inizia a intralciarti, approfondiscilo con git fetch --deepen=<numero> origin o convertiscilo con git fetch --unshallow origin. Di solito è più veloce e più sicuro che combattere errori di cronologia mancante un comando alla volta.