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.
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.