Formations — 1 037 leçons en français

Accueil › Git & CI/CD › Les sous-modules et leurs pièges

Les sous-modules et leurs pièges

Monorepo, sous-modules et gros dépôtsavance

Un sous-module est un dépôt Git dans un dépôt Git. Le parent n'enregistre pas les fichiers : il enregistre un identifiant de commit.

git submodule add git@forge:equipe/charte.git externes/charte
git commit -m "Ajoute la charte graphique en sous-module"

Deux choses sont versionnées dans le parent :

.gitmodules          → le chemin et l'URL (lisible, modifiable)
externes/charte      → un pointeur de commit (invisible, c'est l'essentiel)

Le geste qui manque toujours

git clone --recurse-submodules git@forge:equipe/parent.git
# ou, après un clone ordinaire :
git submodule update --init --recursive

Sans cela, le répertoire du sous-module existe et il est vide. Le clone ne signale rien ; c'est la compilation qui échoue.

Mettre à jour un sous-module

cd externes/charte
git checkout main && git pull
cd ..
git add externes/charte          # on ajoute le pointeur, pas des fichiers
git commit -m "Charte : passe à la version du 12 mars"

Changer de version de sous-module est un commit du parent. C'est ce qui rend la chose reproductible : quiconque extrait ce commit obtient exactement cette version de la charte.

L'ordre des poussées

Poussez le sous-module d'abord, le parent ensuite. L'inverse publie un pointeur vers un commit que personne ne possède.

Les termes à connaître

Sous-module

Un dépôt Git imbriqué dans un autre. Le dépôt parent n'enregistre pas les fichiers du sous-module mais un identifiant de commit : le sous-module est épinglé sur une version précise.

.gitmodules

Fichier versionné, à la racine du parent, qui associe chaque chemin de sous-module à son URL et, éventuellement, à une branche. C'est la seule partie lisible de la configuration.

Pointeur de commit

Ce que le parent stocke réellement pour un sous-module : une entrée d'arbre de type commit. Changer de version de sous-module, c'est faire un commit dans le parent.

git submodule update --init --recursive

Récupère les sous-modules et place chacun sur le commit enregistré par le parent. Sans --init, les répertoires restent vides ; sans --recursive, les sous-modules de sous-modules sont oubliés.

HEAD détachée

L'état normal d'un sous-module après mise à jour : il est positionné sur un commit, pas sur une branche. Un commit fait là sans changer de branche n'est rattaché à rien.

clone --recurse-submodules

Clone le parent et initialise les sous-modules en une commande. Sans cette option, le clone réussit et le projet ne compile pas — le symptôme le plus courant du mécanisme.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.