Récupération partielle d’historique avec le shallow clone

Qu’est-ce qu’un shallow clone ?

Un shallow clone est donc un clonage partiel d’un dépôt Git. Il permet :

• De récupérer uniquement les N derniers commits ;
• De cloner les commits postérieurs à une date précise ;
• De cloner uniquement certaines branches sans tout l’historique global.

Ce type de clonage est utile pour les processus d’intégration continue (CI), de déploiement continu (CD), les builds rapides ou la consultation ponctuelle de l’état actuel d’un projet, ou encore pour une récupération partielle dans le cas de projet monolithique possédant un historique très important.

Quels sont les avantages du clonage partiel ?

• Rapidité ;
• Moins de bande passante utilisée ;
• Moins d’espace disque utilisé.

Quelles sont les limites ?

Il existe toutefois quelques limitations qui peuvent géner votre utilisation du projet :

• Impossible de changer de branche facilement (à moins de les spécifier explicitement) ;
• Certaines commandes Git ne fonctionneront pas (e.g. git blame, git log complet).

Cloner les N derniers commits

Il s’agit d’utiliser la commande habituelle clone avec l’option --depth qui permet de spécifier combien de commits doivent être récupérés depuis l’état actuel de la branche (le N commits les plus récents).

git clone --depth 100 <url-du-depôt>

Ce clonage :

• Récupère les 100 derniers commits de la branche par défaut (main ou master) ;
• Ignore tout l’historique antérieur.

Cloner depuis une date précise

Vous pouvez choisir de cloner l’historique à partir d’une date donnée avec l’option --shallow-since.

git clone --shallow-since="2025-01-01" <url-du-dépôt>

Cela permet de ne récupérer que les commits réalisés à partir du 1er janvier 2025.

Remarque :

• Le format de date peut être YYYY-MM-DD, ou plus détaillé : YYYY-MM-DDTHH:MM:SS.

Cloner une ou plusieurs branches spécifiques

Un shallow clone “classique” ne récupère que la branche par défaut. Pour inclure d’autres branches, utilisez l’option --branch.

Cloner une branche spécifique avec un historique limité

git clone --branch develop --depth 5 <url-du-depôt>

Cloner plusieurs branches (en 2 temps) :

Git ne permet pas directement de faire un shallow clone multi-branches via git clone, mais on peut contourner :

git clone --depth 1 --no-single-branch <url-du-depôt>

Cela récupère les dernières versions de toutes les branches, mais sans l’historique complet.

Si vous avez besoin d’une branche en particulier, mais plus tard :

git fetch --depth 5 origin feat/ma-branche
git checkout feat/ma-branche

Réduire le téléchargement au strict minimum

Vous pouvez choisir d’optimiser encore plus le clonage en ne téléchargeant pas les contenus de fichiers immédiatement.

Imaginons un dépôt contenant de nombreux fichiers binaires, images, ou archives (.zip, .tar.gz) qui ne sont pas utiles pour la majorité des partipant·e·s au projet.

L’objectif serait alors de cloner uniquement les métadonnées et l’historique, sans les contenus/fichiers. On pourra travailler avec l’historique projet et Git téléchargera au fil de l’eau les contenus lorsque nous aurons besoin de les utiliser. Pour ça, on utilise l’option --filter :

git clone --filter=blob:none --depth=1 <url-du-dépôt>

• --filter=blob:none : ignore les blobs (contenu réel des fichiers) dans le clonage initial ;
• --depth=1 : ne récupère que le dernier commit (shallow clone).

Seul l’arbre / l’historique Git est téléchargé (références, structure, noms de fichiers), sans contenu.

Vous pourrez ensuite accéder au contenu à la demande : Git les téléchargera lorsqu’ils seront nécessaires (ie. lors de leur lecture/modification).

Aucun contenu, ou seulement ceux ne dépassant pas une taille donnée

Vous pouvez aller plus loin et demander à Git de ne cloner que les fichiers selon une taille limite :

git clone --filter=blob:limit=1000 --depth=1 <url-du-dépôt>

L’option blob:limit=<n> n’inclut que les blobs de moins de n octets.

Autres cas utiles : mise à jour progressive

Si vous avez cloné avec --depth, vous pouvez étendre l’historique après coup :

git fetch --deepen=20

Ajoute 20 commits de plus à l’historique courant.

Ou pour récupérer l’historique complet :

git fetch --unshallow

Comparaison des options

Cloner uniquement un dossier spécifique

Bien que ce cas sorte quelque peu du contexte de cet article, il est intéressant de savoir que, dans une optique d’optimisation du travail local, on peut choisir de ne travailler que sur une partie de l’arborescence du projet.

Dans l’exemple suivant, on ne récupère que le dossier src/ (et ses fichiers) tout en gardant l’historique Git.

git clone --filter=blob:none --sparse <url-du-dépôt>
cd <nom-du-répertoire-projet>
git sparse-checkout set src/

Nous avions déjà évoqué ce potentiel dans notre article sur le sparse checkout.

Conclusion

Le shallow clone est un outil puissant pour optimiser les performances lors du clonage de dépôts Git volumineux. Bien qu’il limite certaines fonctionnalités Git, il est parfaitement adapté aux pipelines d’intégration continue ou à une analyse partielle du code. Grâce à des options comme --depth, --shallow-since ou --branch, vous pouvez adapter le clonage à vos besoins précis.