Clones superficiels dans Git : quand et comment les utiliser

Les clones superficiels dans Git ne récupèrent qu'une partie de l'historique des commits. Ils sont utiles lorsqu'un travail CI, une étape de déploiement ou une inspection rapide nécessite le code actuel mais pas des années d'historique.

Ils ne sont pas le meilleur choix par défaut pour chaque poste de développeur. Un clone superficiel peut économiser du temps et de l'espace disque, mais il limite également les commandes basées sur l'historique jusqu'à ce que vous récupériez plus de commits.

Qu'est-ce qu'un clone superficiel ?

Un clone standard récupère suffisamment d'historique pour le travail normal sur les branches, l'inspection de l'historique, l'extraction d'anciennes étiquettes et l'investigation hors ligne. Un clone superficiel tronque cet historique à une profondeur que vous choisissez.

Par exemple, --depth 1 récupère le commit de pointe pour la branche sélectionnée. --depth 50 récupère un historique plus récent, mais toujours pas l'ascendance complète.

Avantages de l'utilisation des clones superficiels

Le principal avantage est un coût de transfert réduit :

Extraction initiale plus rapide pour les grands dépôts.
Moins d'utilisation du disque sur les agents de construction éphémères.
Moins de bande passante utilisée sur les réseaux lents ou limités.
Moins d'historique à traiter par Git lors du clone initial.

Dans un pipeline CI qui construit le commit actuel et jette l'espace de travail, un clone superficiel est souvent un gain net.

Inconvénients et limitations des clones superficiels

Le compromis est un historique manquant :

git log s'arrête à la limite superficielle.
git blame peut ne pas être capable de suivre les modifications plus anciennes.
Les anciennes étiquettes ou commits peuvent être indisponibles jusqu'à ce qu'ils soient récupérés.
Les rebases et les fusions peuvent être plus difficiles si Git a besoin d'une base de fusion manquante.
Certains workflows de publication ou d'audit attendent un historique complet.

Si votre travail implique souvent le débogage de régressions anciennes, la préparation de versions ou le rétroportage de modifications, commencez par un clone complet.

Comment créer un clone superficiel

Utilisez git clone --depth :

git clone --depth <nombre> <url_du_dépôt>

Par exemple, pour cloner un dépôt et ne récupérer que les 10 derniers commits :

git clone --depth 10 https://github.com/example/large-repo.git

Pour un travail de construction qui n'a besoin que de la pointe de la branche :

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

Pour cloner une branche spécifique :

git clone --depth 1 -b develop https://github.com/example/project.git

Vous pouvez également ajouter --single-branch lorsque vous ne voulez que l'historique de cette branche :

git clone --depth 1 --single-branch --branch develop https://github.com/example/project.git

Gestion des clones superficiels

Récupérer plus d'historique (approfondir le clone)

Si vous avez besoin de plus d'historique après le clonage, approfondissez le dépôt :

git fetch --deepen=50 origin

Cela récupère 50 commits supplémentaires au-delà de la limite superficielle actuelle.

Vous pouvez également définir la profondeur totale souhaitée :

git fetch --depth=100 origin

Point important : git remote set-depth n'est pas une commande Git valide. La profondeur est contrôlée via les options de clone et de fetch.

Récupérer les étiquettes

Les clones superficiels peuvent ne pas inclure toutes les étiquettes, surtout celles pointant vers des commits plus anciens. Récupérez les étiquettes uniquement si votre workflow en a besoin :

git fetch --tags origin

Désuperficialiser un dépôt

Pour convertir un clone superficiel en clone complet, récupérez le reste de l'historique :

git fetch --unshallow origin

Cette commande téléchargera l'historique restant depuis le dépôt distant.

Pousser depuis un clone superficiel

Pousser depuis un clone superficiel peut fonctionner lorsque vos nouveaux commits sont basés sur la pointe de la branche distante que vous avez récupérée. C'est toujours un mauvais choix pour un développement à long terme car l'historique manquant peut rendre les rebases, la résolution de conflits et la révision plus difficiles.

Si vous rencontrez des problèmes de poussée ou de fusion liés à l'historique, récupérez plus d'historique ou désuperficialisez le clone avant de continuer.

Quand utiliser les clones superficiels

Utilisez-les lorsque le travail est de courte durée et que l'historique n'est pas important :

Extraction CI/CD.
Inspection en lecture seule.
Environnements de reproduction temporaires.
Constructions de documentation.
Grands dépôts sur des réseaux lents.

Quand ne pas utiliser les clones superficiels

Évitez-les lorsque vous avez régulièrement besoin de :

git log, git blame ou git bisect approfondis.
Travail de publication utilisant d'anciennes étiquettes.
Travail complexe de fusion ou de rebase.
Débogage hors ligne à travers l'historique.
Workflows de contribution qui attendent un clone complet.

Conclusion pratique

Utilisez git clone --depth 1 pour les travaux jetables qui n'ont besoin que du dernier code. Utilisez un clone complet pour le développement normal, sauf si vous avez une raison claire de ne pas le faire.

Si un clone superficiel commence à vous gêner, approfondissez-le avec git fetch --deepen=<nombre> origin ou convertissez-le avec git fetch --unshallow origin. C'est généralement plus rapide et plus sûr que de lutter contre les erreurs d'historique manquant une commande à la fois.