Sous-modules, subtrees ou vendoring : trois façons d'inclure un autre dépôt

Ce que c'est

Trois mécanismes permettent de faire entrer le code d'un autre dépôt dans le sien :

• Sous-module (submodule). L'arbre du superprojet contient une entrée gitlink qui porte l'identifiant de commit auquel le sous-module devrait se trouver, et .gitmodules consigne le chemin et l'URL. Le sous-module conserve son propre historique et son propre répertoire Git. La documentation indique qu'après git submodule update, le commit consigné est extrait sur une HEAD détachée.
• Subtree. git subtree add --prefix=<dir> <repository> <ref> importe les fichiers de l'autre projet dans un sous-répertoire sous forme de fichiers suivis ordinaires ; avec --squash, seul un commit unique est importé au lieu de l'historique entier. git subtree pull et git subtree push déplacent les changements dans les deux sens. Le manuel insiste sur le fait que les subtrees n'ont besoin d'aucune construction spéciale telle que .gitmodules ou des gitlinks, et n'imposent rien aux utilisateurs finaux.
• Vendoring. Copier les fichiers, les committer, et consigner la version amont, l'URL source et les éventuels correctifs locaux dans un fichier situé à côté d'eux (VENDOR.md ou un fichier de verrouillage).

Pourquoi c'est important

Ce choix détermine l'apparence d'un clone tout neuf, la façon dont une mise à niveau se déroule, et si des modifications locales sont possibles. Les sous-modules sont exacts mais exigent de chacun, y compris de l'intégration continue, git clone --recurse-submodules ou git submodule update --init --recursive ; oublier cela produit des répertoires vides. Les subtrees et le vendoring produisent un clone autonome, au prix d'un historique plus volumineux et d'une provenance moins évidente.

Comment l'appliquer

• Préférer un gestionnaire de paquets lorsqu'il en existe un pour le langage ; ces trois mécanismes concernent les cas où aucun ne convient (configuration partagée, ressources, un fork privé).
• Utiliser les sous-modules lorsque la dépendance est volumineuse, évolue indépendamment, et doit être fixée sur un commit exact dans lequel on développe également.
• Utiliser les subtrees lorsque les utilisateurs ne devraient pas avoir besoin de le savoir, et que les mises à niveau sont occasionnelles (git subtree pull --squash garde l'historique court).
• Recourir au vendoring lorsque la dépendance est petite et stable ; noter la version et la licence pour que la copie puisse être auditée et actualisée.
• Quel que soit le choix, mettre la commande de mise à niveau dans le README et exécuter la construction depuis un clone tout neuf en intégration continue.

Pièges

Des commits de sous-module poussés vers le superprojet mais pas vers la remote du sous-module cassent tous les autres clones. Les commits effectués à l'intérieur d'un sous-module sur sa HEAD détachée ne reposent sur aucune branche et se perdent facilement, sauf si une branche est créée au préalable. Le manuel des subtrees demande une cohérence avec --squash : si toutes les fusions sont compressées (squashed), split --rejoin doit l'être aussi, sans quoi le journal affiche une copie de chaque commit. Les copies issues du vendoring dérivent silencieusement lorsque quelqu'un les corrige sans mettre à jour le relevé.