HOWTO · Git
Tirez le dernier sous-module Git
Dans cet article, nous présenterons les sous-modules Git.
Sur cette page
Un sous-module Git est un dépôt distinct extrait à l’intérieur d’un dépôt parent. Le parent enregistre un commit précis du sous-module ; « mettre à jour » peut donc vouloir dire rétablir ce commit enregistré ou faire avancer le sous-module vers un commit plus récent de son dépôt distant. Depuis le dépôt parent, utilisez git submodule update --init --recursive pour initialiser les sous-modules manquants et extraire les commits enregistrés par le parent. Pour suivre un commit distant plus récent, utilisez git submodule update --remote --recursive ; examinez ensuite le pointeur du sous-module modifié et validez-le dans le dépôt parent.
Fonctionnement de la mise à jour d’un sous-module Git
Un sous-module possède son propre historique de commits et sa propre configuration distante. Le dépôt parent stocke un gitlink, c’est-à-dire une référence à un commit du dépôt imbriqué. Cloner ou extraire le dépôt parent ne signifie donc pas que le répertoire du sous-module est initialisé ni qu’il suit la pointe d’une branche distante.
git submodule update extrait le commit enregistré par le commit parent courant. C’est le choix reproductible lorsque vous voulez utiliser les dépendances déclarées par le projet. L’option --init enregistre et initialise les sous-modules décrits dans .gitmodules ; --recursive applique aussi l’opération aux sous-modules imbriqués. Ces options ne signifient pas « récupérer le commit le plus récent ».
Initialiser les sous-modules et extraire les commits enregistrés
Exécutez cette commande à la racine du dépôt parent après un nouveau clonage sans initialisation des sous-modules, ou après avoir extrait un commit parent qui en contient :
git submodule update --init --recursive
Git initialise au besoin les chemins configurés et extrait chaque commit enregistré par le parent. Si un sous-module est déjà initialisé, la commande ramène tout de même son répertoire de travail au commit enregistré. Cette extraction peut laisser le sous-module en HEAD détachée ; c’est normal lorsqu’il se trouve sur un commit épinglé par son parent. Pour repérer les pointeurs de sous-modules qui diffèrent de ceux du commit parent courant, examinez git status dans le dépôt parent.
Récupérer des commits distants plus récents pour les sous-modules
Pour mettre à jour les sous-modules à partir de leurs branches de suivi distantes configurées, exécutez git submodule update --remote --recursive depuis le dépôt parent. Git récupère les données du dépôt distant configuré et extrait le commit sélectionné par la branche configurée pour le sous-module. Si aucune branche n’est indiquée pour un sous-module, Git utilise la branche par défaut de son dépôt distant. Cela ne garantit pas le commit le plus récent de chaque branche ou de chaque dépôt distant : le résultat dépend de la branche configurée et de l’état récupéré de sa branche de suivi distante.
Une mise à jour distante modifie le commit extrait dans le sous-module et fait apparaître le pointeur de celui-ci comme modifié dans le dépôt parent. Examinez ce changement avant de le valider. Si vous souhaitez uniquement récupérer les données distantes sans changer le commit extrait, faites la récupération dans le sous-module et examinez ses branches au lieu d’utiliser --remote pour effectuer une extraction.
Cloner un dépôt avec ses sous-modules
Pour cloner un dépôt et initialiser ses sous-modules récursivement en une seule étape, utilisez git clone --recurse-submodules <repository-url>. Remplacez l’espace réservé par l’URL du dépôt. Un simple git clone <repository-url> récupère le dépôt parent, mais n’initialise pas les répertoires de travail de ses sous-modules ; après ce clonage, exécutez git submodule update --init --recursive depuis le nouveau répertoire parent.
L’option récursive initialise aussi les sous-modules imbriqués dans d’autres sous-modules. L’extraction suit les commits enregistrés par le dépôt parent cloné. Cette méthode convient donc lorsque vous voulez les versions sélectionnées par le projet.
Valider et pousser les changements d’un sous-module
Lorsque vous modifiez un sous-module, validez et poussez d’abord le changement depuis le dépôt de ce sous-module. Un sous-module extrait au commit épinglé par son parent peut être en HEAD détachée ; choisissez donc la branche distante à utiliser avant de publier le changement. Si celui-ci doit rejoindre une branche existante, basculez sur cette branche et intégrez-y le changement ; sinon, créez une branche. Vérifiez la configuration du dépôt distant et de la branche du sous-module, et confirmez qu’il s’agit bien de la branche que les collaborateurs doivent utiliser. Ajoutez ensuite le changement avec git add, validez-le avec git commit, puis poussez la branche, par exemple avec git push <remote> <branch>. Si vous gardez volontairement HEAD détachée, publiez explicitement son commit courant avec git push <remote> HEAD:<branch>, en remplaçant les espaces réservés par le dépôt distant choisi et la branche de destination. Assurez-vous que les collaborateurs qui récupéreront le dépôt parent pourront accéder au commit poussé.
Ne revenez au dépôt parent qu’une fois le commit du sous-module publié. Son état indique alors que le pointeur du sous-module a changé ; indexez ce chemin et validez le dépôt parent, par exemple avec git add path/to/submodule, puis git commit -m "Update submodule pointer". Poussez séparément le commit parent, comme d’habitude. Le commit parent enregistre le nouvel identifiant du commit du sous-module, tandis que ce commit appartient au dépôt imbriqué. Pousser uniquement le dépôt parent ne publie pas un commit du sous-module qui n’a pas déjà été poussé ; pousser uniquement le sous-module ne modifie pas le commit enregistré par le parent.