Sous-module Git

Qu’est-ce qu’un sous-module

Très souvent, un dépôt de code dépend de code externe provenant d’autres dépôts. Vous pouvez copier-coller directement le code externe dans le dépôt principal, ou utiliser le système de gestion de paquets d’un langage. Cependant, ces deux méthodes ont l’inconvénient de ne pas suivre les changements du dépôt externe. Git permet d’inclure d’autres dépôts Git, appelés sous-modules, dans un seul dépôt. Les sous-modules permettent de suivre les changements à travers plusieurs dépôts depuis un dépôt parent unique. Les sous-modules sont des dépôts inclus dans le dépôt parent à un chemin spécifique dans le répertoire de travail. Ils peuvent se trouver n’importe où dans le répertoire de travail et sont configurés via le fichier .gitmodules, situé à la racine du dépôt parent. Le fichier .gitmodules contient des métadonnées sur le mappage entre l’URL du projet du sous-module et le répertoire local. Les sous-modules prennent en charge l’ajout, la synchronisation, la mise à jour et le clonage. Les sous-modules ne suivent que des commits spécifiques, et non des références Git ni des branches.

Quand utiliser les sous-modules

Travailler avec des sous-modules est délicat, c’est pourquoi nous suggérons quelques cas d’utilisation adaptés.

• Si le sous-projet évolue trop vite ou si des changements à venir risquent de casser l’API, verrouillez le code sur un commit spécifique pour plus de sécurité.
• Si un composant n’est pas mis à jour très souvent et que vous souhaitez le suivre comme une dépendance externe.
• Si vous représentez une partie du projet auprès d’un tiers et que vous souhaitez intégrer leur travail à un moment précis (cela fonctionne seulement lorsque les mises à jour ne sont pas trop fréquentes).
• Si le contexte technologique permet l’empaquetage et une gestion formelle des dépendances, vous devriez utiliser des gestionnaires de paquets plutôt que des sous-modules.
• Si votre base de code est massive et que vous ne voulez pas la récupérer à chaque fois, utilisez des sous-modules pour éviter que les collaborateurs téléchargent l’ensemble de la base de code.

Commandes pour les sous-modules Git

Pour créer un nouveau sous-module dans un dépôt existant, utilisez git submodule add.

créer un nouveau sous-module dans le dépôt git existant

mkdir git-submodule-demo
cd git-submodule-demo/
git init

Initialized empty Git repository in /Users/example/git-submodule-demo/.git/

Pour ajouter un sous-module au nouveau dépôt, exécutez ce qui suit :

ajouter un sous-module au nouveau dépôt git

git submodule add https://somehost/example/textexample

Cloning into '/Users/example/git-submodule-demo/textexample'...
remote: Counting objects: 8, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 8 (delta 1), reused 0 (delta 0)
Unpacking objects: 100% (8/8), done.

La commande git submodule add prend une URL pointant vers un dépôt Git. Git clone immédiatement le sous-module textexample. Vérifiez l’état du dépôt en exécutant la commande git status :

vérifier l’état du dépôt git status

git status

On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

 new file: .gitmodules
 new file: textexample

Vous pouvez valider les fichiers dans le dépôt à l’aide des commandes git add et git commit :

valider les fichiers git

git add .gitmodules textexample/
git commit -m "added submodule"

[master (root-commit) d5002d0] added submodule
 2 files changed, 4 insertions(+)
 create mode 100644 .gitmodules
 create mode 160000 textexample

Mise à jour des sous-modules

Les membres de l’équipe doivent mettre à jour le code du sous-module s’il a été modifié ailleurs. Vous ne pouvez pas utiliser git pull, car cette commande met uniquement à jour la référence du dépôt parent vers le commit du sous-module, et non le code réel du sous-module. Pour mettre à jour le sous-module vers le commit enregistré, exécutez :

mise à jour du code du sous-module git

git submodule update

Remarque : sans l’option --remote, cette commande ne vérifie que le commit enregistré dans le dépôt parent et ne récupère pas les nouvelles modifications en amont.

Si le fichier .gitmodules est mis à jour (par exemple, si l’URL du sous-module change), exécutez git submodule sync pour mettre à jour le .git/config local avec les nouvelles URL avant d’exécuter git submodule update.

Clonage des sous-modules Git

Pour cloner un projet avec des sous-modules, utilisez la commande git clone. Par défaut, elle clone le dépôt parent mais laisse les répertoires des sous-modules vides. Vous devez ensuite exécuter git submodule init et git submodule update. La première commande met à jour le .git/config local avec les correspondances provenant de .gitmodules, tandis que la seconde récupère les données du sous-module et vérifie le commit enregistré.

Sinon, utilisez l’option --recursive avec git clone pour initialiser et mettre à jour automatiquement les sous-modules. Si vous avez cloné sans --recursive, exécutez ce qui suit :

la commande git clone initialise et met à jour les sous-modules

git clone /url/to/repo/with/submodules
git submodule init
git submodule update

Récupération du code du sous-module

Lorsque vous récupérez un dépôt contenant de nouveaux sous-modules, les autres membres de l’équipe doivent les initialiser. Commencez par exécuter git pull pour récupérer l’état le plus récent du dépôt parent. Si de nouveaux sous-modules sont सूचीés, initialisez-les avec :

initialiser de nouveaux sous-modules git

git submodule init

Notez que init met uniquement à jour le fichier local .git/config. Pour récupérer réellement le code et vérifier le commit enregistré, vous devez exécuter git submodule update.

Pousser les mises à jour dans le sous-module

Comme un sous-module est un dépôt séparé, vous pouvez y pousser des modifications comme dans n’importe quel dépôt Git en exécutant des commandes à l’intérieur du répertoire du sous-module. Si vous créez de nouveaux commits dans le sous-module, le dépôt parent pointera toujours vers l’ancien commit. Pour mettre à jour le dépôt parent vers le nouveau commit, exécutez git add sur le répertoire du sous-module, validez, puis poussez. Lorsque vous exécutez git status dans le dépôt principal, le sous-module apparaîtra comme « Changes not staged for commit » avec le message « modified content (new commits) ». Cela indique que le code du sous-module est vérifié à un commit différent de celui attendu par le dépôt parent.

Les sous-modules sont un bon moyen de conserver des projets dans des dépôts séparés tout en les référençant comme des dossiers dans le répertoire de travail d’un autre dépôt. Cependant, gardez à l’esprit que pour de nombreux projets, les sous-modules ne constituent pas la meilleure pratique, et qu’il peut être délicat de travailler avec eux.

Practice

Quels sont les aspects clés de l’utilisation des sous-modules Git ?

Les sous-modules Git permettent d’inclure d’autres dépôts dans un dépôt parent et de suivre les changements dans plusieurs dépôts via un seul dépôt.La commande 'git submodule add' est utilisée pour copier-coller du code externe dans le dépôt principal.Le fichier '.gitmodules' contient des métadonnées sur le mappage entre l’URL du sous-module et le répertoire local.Les sous-modules sont mis à jour automatiquement lorsque le dépôt parent est mis à jour avec 'git pull'.Pour mettre à jour le code d’un sous-module, la commande 'git submodule update' doit être utilisée.Cloner un dépôt avec des sous-modules nécessite d’exécuter 'git clone', puis 'git submodule init' et 'git submodule update'.Les modifications apportées à l’intérieur d’un sous-module peuvent être poussées directement depuis le répertoire du sous-module.