7.11 Utilitaires Git - Sous-modules

Le modèle le plus simple d’utilisation des sous-modules est le cas de la simple consommation d’un sous-projet duquel on souhaite obtenir les mises à jour de temps en temps mais auquel on n’apporte pas de modification dans la copie de travail. Examinons un exemple simple.

Quand vous souhaitez vérifier si le sous-module a évolué, vous pouvez vous rendre dans le répertoire correspondant et lancer git fetch puis git merge de la branche amont pour mettre à jour votre code local.

Si vous revenez maintenant dans le projet principal et lancez git diff --submodule, vous pouvez remarquer que le sous-module a été mis à jour et vous pouvez obtenir une liste des commits qui y ont été ajoutés. Si vous ne voulez pas taper --submodule à chaque fois que vous lancez git diff, vous pouvez le régler comme format par défaut en positionnant le paramètre de configuration diff.submodule à la valeur « log ».

Si vous validez à ce moment, vous fixez la version du sous-module à la version actuelle quand d’autres personnes mettront à jour votre projet.

Il existe aussi un moyen plus facile, si vous préférez ne pas avoir à récupérer et fusionner manuellement les modifications dans le sous-répertoire. Si vous lancez la commande git submodule update --remote, Git se rendra dans vos sous-modules et réalisera automatiquement le fetch et le merge.

Cette commande considère par défaut que vous souhaitez mettre à jour la copie locale vers la branche master du dépôt du sous-module. Vous pouvez, cependant, indiquer une autre branche. Par exemple, si le sous-module DbConnector suit la branche stable du dépôt amont, vous pouvez l’indiquer soit dans votre fichier .gitmodules (pour que tout le monde le suive de même) ou juste dans votre fichier local .git/config. Voyons ceci dans le cas du fichier .gitmodules :

Si vous ne spécifiez pas la partie -f .gitmodules, la commande ne fera qu’une modification locale, mais il semble plus logique d’inclure cette information dans l’historique du projet pour que tout le monde soit au diapason.

Quand vous lancez git status, Git vous montrera que nous avons de nouveaux commits (« new commits ») pour le sous-module.

Si vous activez le paramètre de configuration status.submodulesummary, Git vous montrera aussi un résumé des modifications dans vos sous-modules :

Ici, si vous lancez git diff, vous pouvez voir que le fichier .gitmodules a été modifié mais aussi qu’il y a un certain nombre de commits qui ont été tirés et sont prêts à être validés dans le projet du sous-module.

C’est une information intéressante car vous pouvez voir le journal des modifications que vous vous apprêtez à valider dans votre sous-module. Une fois validées, vous pouvez encore visualiser cette information en lançant git log -p.

Par défaut, Git essaiera de mettre à jour tous les sous-modules lors d’une commande git submodule update --remote, donc si vous avez de nombreux sous-modules, il est préférable de spécifier le sous-module que vous souhaitez mettre à jour.

Glissons-nous maintenant dans les habits d’un collaborateur, qui a son propre clone local du dépôt ProjetPrincipal. Lancer simplement git pull pour obtenir les nouvelles modifications validées ne suffit plus :

Par défaut, la commande git pull récupère les modifications des sous-modules récursivement, comme nous pouvons le voir sur la première ligne ci-dessus. Cependant, elle ne met pas les sous-modules à jour. C’est affiché à la sortie de la commande git status, qui indique que le sous-module est « modified », et a des nouveaux commit (new commits). De plus, les chevrons indiquant les nouveaux commits pointent à gauche (<), ce qui signifie que ces commits sont enregistrés dans ProjetPrincipal, mais ne sont pas présents dans l’extraction locale de DbConnector. Pour finaliser la mise à jour, vous devez lancer git submodule update :

Notez que pour rester en sécurité, vous devriez lancer git submodule update avec le drapeau --init au cas où les commits de ProjetPrincipal que vous venez de tirer ont ajouté des nouveaux sous-modules, et le drapeau --recursive si certains sous-module ont des sous-modules imbriqués.

Si vous souhaitez automatiser ce processsus, vous pouvez ajouter le drapeau --recurse-submodules à la commande git pull (depuis Git 2.14). Cela forcera Git à lancer git submodule update juste après le tirage, de manière à mettre à jour les sous-modules dans l’état correct. De plus, si vous voulez que Git tire toujours avec --recurse-submodules, vous pouvez régler l’option de configuration submodule.recurse à true (cela marche pour git pull depuis Git 2.15). Cette option forcera Git à utiliser le drapeau --recurse-submodules pour toutes les commandes qui le supportent (à part clone).

Il y a une situation spéciale qui peut arriver lors du tirage depuis le super-projet ; le dépôt amont peut avoir modifié l’URL du sous-module dans le fichier .gitmodules dans un des commits que vous tirez. Cela peut arriver si le projet du sous-module change de plate-forme d’hébergement. Dans ce dernier cas, il est possible pour git pull --recurse-submodules, or git submodule update, d’échouer si le super-projet fait référence à un commit d’un sous-module qui n’est pas trouvé dans le serveur distant du sous-module configuré localement dans votre dépôt. Pour corriger cette situation, la commande git submodule sync est nécessaire :

Il y a fort à parier que si vous utilisez des sous-modules, vous le faites parce que vous souhaitez en réalité travailler sur le code du sous-module en même temps que sur celui du projet principal (ou à travers plusieurs sous-modules). Sinon, vous utiliseriez plutôt un outil de gestion de dépendances plus simple (tel que Maven ou Rubygems).

De ce fait, détaillons un exemple de modifications réalisées dans le sous-module en même temps que dans le projet principal et de validation et de publication des modifications dans le même temps.

Jusqu’à maintenant, quand nous avons lancé la commande git submodule update pour récupérer les modifications depuis les dépôts des sous-modules, Git récupérait les modifications et mettait les fichiers locaux à jour mais en laissant le sous-répertoire dans un état appelé « HEAD détachée ». Cela signifie qu’il n’y pas de branche locale de travail (comme master, par exemple) pour y valider les modifications. Donc, toutes les modifications que vous y faites ne sont pas suivies non plus.

Pour rendre votre sous-module plus adapté à la modification, vous avez besoin de deux choses. Vous devez vous rendre dans chaque sous-module et extraire une branche de travail. Ensuite vous devez dire à Git ce qu’il doit faire si vous avez réalisé des modifications et que vous lancez git submodule update --remote pour tirer les modifications amont. Les options disponibles sont soit de les fusionner dans votre travail local, soit de tenter de rebaser le travail local par dessus les modifications distantes.

En premier, rendons-nous dans le répertoire de notre sous-module et extrayons une branche.

Attaquons-nous au choix de politique de gestion. Pour le spécifier manuellement, nous pouvons simplement ajouter l’option --merge à l’appel de update. Nous voyons ici qu’une modification était disponible sur le serveur pour ce sous-module et qu’elle a été fusionnée.

Si nous nous rendons dans le répertoire DbConnector, les nouvelles modifications sont déjà fusionnées dans notre branche locale stable. Voyons maintenant ce qui arrive si nous modifions localement la bibliothèque et que quelqu’un pousse une autre modification en amont dans le même temps.

Maintenant, si nous mettons à jour notre sous-module, nous pouvons voir ce qui arrive lors d’un rebasage de deux modifications concurrentes.

Si vous oubliez de spécifier --rebase ou --merge, Git mettra juste à jour le sous-module vers ce qui est sur le serveur et réinitialisera votre projet à l’état « HEAD détachée ».

Si cela arrive, ne vous inquiétez pas, vous pouvez simplement revenir dans le répertoire et extraire votre branche (qui contiendra encore votre travail) et fusionner ou rebaser origin/stable (ou la branche distante que vous souhaitez) à la main.

Si vous n’avez pas validé vos modifications dans votre sous-module, et que vous lancez une mise à jour de sous-module qui causerait des erreurs, Git récupérera les modifications mais n’écrasera pas le travail non validé dans votre répertoire de sous-module.

Si vous avez réalisé des modifications qui entrent en conflit avec des modifications amont, Git vous en informera quand vous mettrez à jour.

Vous pouvez vous rendre dans le répertoire du sous-module et résoudre le conflit normalement.

Nous avons donc des modifications dans notre répertoire de sous-module, venant à la fois du dépôt amont et de modifications locales non publiées.

Si nous validons dans le projet principal et que nous le poussons en amont sans pousser les modifications des sous-modules, les autres personnes qui voudront essayer notre travail vont avoir de gros problèmes vu qu’elles n’auront aucun moyen de récupérer les modifications des sous-modules qui en font partie. Ces modifications n’existent que dans notre copie locale.

Pour être sur que cela n’arrive pas, vous pouvez demander à Git de vérifier que tous vos sous-modules ont été correctement poussés avant de pouvoir pousser le projet principal. La commande git push accepte un argument --recurse-submodules qui peut avoir pour valeur « check » ou « on-demand ». L’option « check » fera échouer push si au moins une des modifications des sous-modules n’a pas été poussée.

Comme vous pouvez le voir, il donne aussi quelques conseils utiles sur ce que nous pourrions vouloir faire ensuite. L’option simple consiste à se rendre dans chaque sous-module et à pousser manuellement sur les dépôts distants pour s’assurer qu’ils sont disponibles publiquement, puis de réessayer de pousser le projet principal.

L’autre option consiste à utiliser la valeur « on-demand » qui essaiera de faire tout ceci pour vous.

Comme vous pouvez le voir, Git s’est rendu dans le module DbConnector et l’a poussé avant de pousser le projet principal. Si la poussée du sous-module échoue pour une raison quelconque, la poussée du projet principal sera annulée.

Si vous changez la référence d’un sous-module en même temps qu’une autre personne, il se peut que cela pose problème. Particulièrement, si les historiques des sous-modules ont divergé et sont appliqués à des branches divergentes dans un super-projet, rapprocher toutes les modifications peut demander un peu de travail.

Si un des commits est un ancêtre direct d’un autre (c’est-à-dire une fusion en avance rapide), alors Git choisira simplement ce dernier pour la fusion et cela se résoudra tout seul.

Cependant, Git ne tentera pas de fusion, même très simple, pour vous. Si les commits d’un sous-module divergent et doivent être fusionnés, vous obtiendrez quelque chose qui ressemble à ceci :

Donc, ce qui s’est passé en substance est que Git a découvert que les deux points de fusion des branches à fusionner dans l’historique du sous-module sont divergents et doivent être fusionnés. Il l’explique par « merge following commits not found » (fusion suivant les commits non trouvée), ce qui n’est pas clair mais que nous allons expliquer d’ici peu.

Pour résoudre le problème, vous devez comprendre l’état dans lequel le sous-module devrait se trouver. Étrangement, Git ne vous donne pas d’information utile dans ce cas, pas même les SHA-1 des commits des deux côtés de l’historique. Heureusement, c’est assez facile à comprendre. Si vous lancez git diff, vous pouvez obtenir les SHA-1 des commits enregistrés dans chacune des branches que vous essayiez de fusionner.

Donc, dans ce cas, eb41d76 est le commit dans notre sous-module que nous avions et c771610 est le commit amont. Si nous nous rendons dans le répertoire du sous-module, il devrait déjà être sur eb41d76 parce que la fusion ne l’a pas touché. S’il n’y est pas, vous pouvez simplement créer et extraire une branche qui pointe dessus.

Ce qui importe, c’est le SHA-1 du commit venant de l’autre branche. C’est ce que nous aurons à fusionner. Vous pouvez soit essayer de fusionner avec le SHA-1 directement ou vous pouvez créer une branche à partir du commit puis essayer de la fusionner. Nous suggérons d’utiliser cette dernière méthode, ne serait-ce que pour obtenir un message de fusion plus parlant.

Donc, rendons-nous dans le répertoire du sous-module, créons une branche basée sur ce second SHA-1 obtenu avec git diff et fusionnons manuellement.

Nous avons eu un conflit de fusion ici, donc si nous le résolvons et validons, alors nous pouvons simplement mettre à jour le projet principal avec le résultat.

Cela peut paraître compliqué mais ce n’est pas très difficile.

Curieusement, il existe un autre cas que Git gère seul. Si un commit de fusion existe dans le répertoire du sous-module qui contient les deux commits dans ses ancêtres, Git va le suggérer comme solution possible. Il voit qu’à un certain point de l’historique du projet du sous-module, quelqu’un a fusionné les branches contenant ces deux commits, donc vous désirerez peut-être utiliser celui-ci.

C’est pourquoi le message d’erreur précédent s’intitulait « merge following commits not found », parce que justement, il ne pouvait pas trouver le commit de fusion. C’est déroutant car qui s’attendrait à ce qu’il essaie de le chercher ?

S’il trouve un seul commit de fusion acceptable, vous verrez ceci :

Ce qu’il suggère de faire est de mettre à jour l’index comme si vous aviez lancé git add, ce qui élimine le conflit, puis de valider. Vous ne devriez cependant pas le faire. Vous pouvez plus simplement vous rendre dans le répertoire du sous-module, visualiser la différence, avancer en avance rapide sur le commit, le tester puis le valider.

Cela revient au même, mais de cette manière vous pouvez au moins vérifier que ça fonctionne et vous avez le code dans votre répertoire de sous-module quand c’est terminé.

Il existe une commande submodule foreach qui permet de lancer une commande arbitraire dans chaque sous-module. C’est particulièrement utile si vous avez plusieurs sous-modules dans le même projet.

Par exemple, supposons que nous voulons développer une nouvelle fonctionnalité ou faire un correctif et que nous avons déjà du travail en cours dans plusieurs sous-modules. Nous pouvons facilement remiser tout le travail en cours dans tous les sous-modules.

Ensuite, nous pouvons créer une nouvelle branche et y basculer dans tous nos sous-modules.

Vous comprenez l’idée. Une commande vraiment utile permet de produire un joli diff unifié des modifications dans le projet principal ainsi que dans tous les sous-projets.

Ici, nous pouvons voir que nous définissons une fonction dans un sous-module et que nous l’appelons dans le projet principal. C’est un exemple exagérément simplifié, mais qui aide à mieux comprendre l’utilité de cette commande.

Vous pourriez être intéressé de définir quelques alias pour des commandes longues pour lesquelles vous ne pouvez pas régler la configuration par défaut. Nous avons traité la définition d’alias Git dans Les alias Git, mais voici un exemple d’alias que vous pourriez trouver utiles si vous voulez travailler sérieusement avec les sous-modules de Git.

De cette manière, vous pouvez simplement lancer git supdate lorsque vous souhaitez mettre à jour vos sous-module ou git spush pour pousser avec une gestion de dépendance de sous-modules.

Commuter des branches qui contiennent des sous-modules peut également s’avérer difficile. Si vous créez une nouvelle branche, y ajoutez un sous-module, et revenez ensuite à une branche dépourvue de ce sous-module, vous aurez toujours le répertoire de ce sous-module comme un répertoire non suivi :

Supprimer le répertoire n’est pas difficile, mais sa présence est assez déroutante. Si vous le supprimez puis que vous rebasculez sur la branche qui contient le sous-module, vous devrez lancer submodule update --init pour le réalimenter.

Une fois de plus, ce n’est pas réellement difficile, mais cela peut être déroutant.

Les nouvelles versions de Git (Git >= 2.13) simplifie tout ceci en ajoutant le drapeau --recurse-submodules à la commande git checkout, qui s’occupe de placer les sous-modules dans le bon état pour la branche sur laquelle nous commutons.

Utiliser le drapeau --recurse-submodules de git checkout peut aussi être utile quand vous travaillez sur plusieurs branches dans les super-projet, chacune aillant votre sous-module pointant sur des commits différents. En fait, si vous commutez de branches qui enregistrent le sous-module à différents commits, à l’exécution de git status le sous-module apparaîtra comme « modified », et indique « new commits » (nouveaux commits). C’est parce que l’état du sous-module n’est pas géré par défaut lors du basculement de branches.

Cela peut être vraiment déroutant, donc c’est toujours une bonne idée de toujours lancer git checkout --recurse-submodules quand votre projet a des sous-modules. Pour les versions anciennes de Git qui n’ont pas de drapeau --recurse-submodules, après l’extraction, vous pouvez utiliser git submodule update --init --recursive pour placer les sous-modules dans le bon état.

Par chance, vous pouvez indiquer à Git (>=2.14) de toujours utiliser le drapeau --recurse-submodules en paramétrant l’option de configuration submodule.recurse : git config submodule.recurse true. Comme noté ci-dessus, cela forcera auss Git à parcourir récursivement les sous-modules pour toute commande qui accepte l’option --recurse-submodules (excepté git clone).

Une autre difficulté commune consiste à basculer de sous-répertoires en sous-modules. Si vous suiviez des fichiers dans votre projet et que vous voulez les déplacer dans un sous-module, vous devez être très prudent ou Git sera inflexible. Présumons que vous avez les fichiers dans un sous-répertoire de votre projet, et que vous voulez les transformer en un sous-module. Si vous supprimez le sous-répertoire et que vous exécutez submodule add, Git vous hurle dessus avec :

Vous devez d’abord supprimer le répertoire CryptoLibrary de l’index. Vous pourrez ensuite ajouter le sous-module :

Maintenant, supposons que vous avez fait cela dans une branche. Si vous essayez de basculer dans une ancienne branche où ces fichiers sont toujours dans l’arbre de projet plutôt que comme sous-module, vous aurez cette erreur :

Vous pouvez le forcer à basculer avec checkout -f, mais soyez attentif à ce qu’il soit propre ou les modifications seraient écrasées.

Ensuite, lorsque vous rebasculez, vous aurez un répertoire CryptoLibrary vide et git submodule update pourrait ne pas le remettre en état. Vous allez devoir vous rendre dans le répertoire de votre sous-module et lancer git checkout . pour retrouver tous vos fichiers. Vous pouvez lancer ceci dans un script submodule foreach dans le cas de multiples sous-modules.

Il est important de noter que depuis les versions de Git récentes, les sous-modules conservent leurs données Git dans le répertoire .git du projet principal, ce qui à la différence des versions antérieures, permet de supprimer le dossier du sous-module sans perdre les commits et les branches qu’il contenait.

Avec ces outils, les sous-modules peuvent être une méthode assez simple et efficace pour développer simultanément sur des projets connexes mais séparés.