Définition

Un sous-module (submodule) dans Git est un dépôt Git imbriqué à l'intérieur d'un autre dépôt Git. Les sous-modules permettent d'intégrer et de gérer un dépôt Git distinct comme une partie d'un autre dépôt. Cela est particulièrement utile lorsque vous souhaitez inclure un projet externe dans un autre projet, tout en conservant les deux projets séparés.

Principe de fonctionnement

• Ajout d'un sous-module : Vous pouvez ajouter un sous-module à un dépôt Git en utilisant la commande git submodule add URL_du_dépôt. Cela crée un répertoire dans votre dépôt principal qui pointe vers un autre dépôt Git.
• Synchronisation des sous-modules : Lorsque vous clonez un dépôt contenant des sous-modules, les sous-modules ne sont pas automatiquement clonés. Vous devez utiliser la commande git submodule init pour initialiser les sous-modules, puis git submodule update pour les mettre à jour ou les cloner.
• Gestion des versions : Les sous-modules sont liés à une révision spécifique du dépôt imbriqué. Vous pouvez donc contrôler quelle version du sous-module est utilisée dans votre projet.

Utilisation des sous-modules

Les sous-modules sont particulièrement utiles dans les cas où vous travaillez sur des projets complexes dépendant d'autres projets, ou lorsque vous voulez partager un ensemble de bibliothèques ou de composantes entre différents projets sans les dupliquer.

Mise en situation

Il arrive souvent que lorsque vous travaillez sur un projet, vous ayez besoin d'utiliser un autre projet à partir de celui-ci. Il peut s'agir d'une bibliothèque développée par un tiers ou que vous développez séparément et que vous utilisez dans plusieurs projets parents. Un problème courant se pose dans ces scénarios : vous souhaitez pouvoir traiter les deux projets comme des projets distincts tout en étant en mesure d'utiliser l'un à partir de l'autre.

Voici un exemple. Supposons que vous développiez un site Web et que vous créiez des flux Atom. Au lieu d'écrire votre propre code générateur d'Atom, vous décidez d'utiliser une bibliothèque. Vous devrez probablement inclure ce code à partir d'une bibliothèque partagée comme une installation CPAN ou un gem de Ruby, ou copier le code source dans votre propre arborescence de projet. Le problème avec l'inclusion de la bibliothèque est qu'il est difficile de personnaliser la bibliothèque de quelque manière que ce soit et souvent plus difficile de la déployer, car vous devez vous assurer que chaque client dispose de cette bibliothèque. Le problème avec la copie du code dans votre propre projet est que toutes les modifications personnalisées que vous apportez sont difficiles à fusionner lorsque les modifications en amont deviennent disponibles.

Git résout ce problème à l'aide de sous-modules (submodule). Les sous-modules vous permettent de conserver un dépôt Git en tant que sous-répertoire d'un autre dépôt Git. Cela vous permet de cloner un autre dépôt dans votre projet et de conserver vos commits séparés.

Commencer par les sous-modules

Nous allons voir comment développer un projet simple ayant été divisé en un projet principal et quelques sous-projets.

Commençons par ajouter un dépôt Git existant en tant que sous-module du dépôt sur lequel nous travaillons. Pour ajouter un nouveau sous-module, utilisez la commande git submodule add avec l'URL absolue ou relative du projet que vous souhaitez commencer à suivre. Dans cet exemple, nous allons ajouter une bibliothèque appelée «MonSousModule» :

on obtiendra un résultat ressemblant à ceci :

Par défaut, les sous-modules ajouteront le sous-projet dans un répertoire portant le même nom que le dépôt, dans ce cas «MonSousModule». Vous pouvez ajouter un chemin différent à la fin de la commande si vous souhaitez qu'il aille ailleurs.

Si vous exécutez git status à ce stade, vous remarquerez quelques éléments :

on obtiendra un résultat ressemblant à ceci :

Vous devriez d'abord remarquer le nouveau fichier .gitmodules. Il s'agit d'un fichier de configuration entreposant la cartographie entre l'URL du projet et le sous-répertoire local dans lequel vous l'avez extrait :

Remarque : Étant donné que l'URL du fichier .gitmodules est celle que les autres personnes essaieront d'abord de cloner/récupérer, assurez-vous d'utiliser une URL à laquelle elles peuvent accéder si possible. Par exemple, si vous utilisez une URL différente de celle à laquelle les autres personnes auraient accès pour effectuer le push, utilisez celle à laquelle les autres ont accès. Vous pouvez remplacer cette valeur localement avec git config submodule.MonSousModule.url PRIVATE_URL pour votre propre usage. Le cas échéant, une URL relative peut être utile.

L'autre liste dans la sortie de git status est l'entrée du dossier du projet. Si vous exécutez git diff dessus, vous voyez quelque chose d'intéressant :

on obtiendra un résultat ressemblant à ceci :

Bien que MonSousModule soit un sous-répertoire de votre répertoire de travail, Git le considère comme un sous-module et ne suit pas son contenu lorsque vous n'êtes pas dans ce répertoire. Au lieu de cela, Git le considère comme un commit particulier de ce dépôt.

Si vous souhaitez une sortie de diff un peu plus agréable, vous pouvez passer l'option --submodule à git diff :

on obtiendra un résultat ressemblant à ceci :

Lorsque vous vous engagez, vous voyez quelque chose comme ceci :

on obtiendra un résultat ressemblant à ceci :

Notez le mode 160000 pour l'entrée MonSousModule. Il s'agit d'un mode spécial dans Git signifiant essentiellement que vous enregistrez un commit en tant qu'entrée de répertoire plutôt qu'en tant que sous-répertoire ou fichier.

Enfin, appliquez ces modifications :

Cloner un projet avec des sous-modules

Nous allons ici cloner un projet contenant un sous-module. Lorsque vous clonez un tel projet, vous obtenez par défaut les répertoires contenant les sous-modules, mais aucun des fichiers qu'ils contiennent encore :

on obtiendra un résultat ressemblant à ceci :

Ensuite, vous allez voir dans le projet principal :

on obtiendra un résultat ressemblant à ceci :

Ensuite, vous allez voir dans le projet MonSousModule :

Le répertoire MonSousModule est présent, mais vide. Vous devez exécuter deux commandes : git submodule init pour initialiser votre fichier de configuration local et git submodule update pour récupérer toutes les données de ce projet et extraire le commit approprié répertorié dans votre super projet :

on obtiendra un résultat ressemblant à ceci :

Ensuite, vous le mettez à jour :

on obtiendra un résultat ressemblant à ceci :

Votre sous-répertoire MonSousModule est désormais dans l'état exact où il se trouvait lorsque vous avez effectué votre commit plus tôt.

Il existe cependant une autre façon de procéder, un peu plus simple. Si vous passez --recurse-submodules à la commande git clone, elle initialisera et mettra automatiquement à jour chaque sous-module du dépôt, y compris les sous-modules imbriqués si l'un des sous-modules du dépôt en possède lui-même :

on obtiendra un résultat ressemblant à ceci :

Si vous avez déjà cloné le projet et oublié --recurse-submodules, vous pouvez combiner les étapes git submodule init et git submodule update en exécutant git submodule update --init. Pour initialiser, récupérer et extraire également tous les sous-modules imbriqués, vous pouvez utiliser la méthode infaillible git submodule update --init --recursive.