Git possède 2 notions qui permettent d'inclure un repo dans un repo 🙄 pour par exemple mutualiser des sources ou du contenu markdown :

• git submodule
• git subtree

Différence entre subtree et submodule

TLDR : favoriser un subtree pour un workflow simplifié

Git submodules are simply a reference to another repository at a particular snapshot in time.

- Atlassian

Git subtree lets you nest one repository inside another as a sub-directory.

- Atlassian

Donc les submodules permettent de référencer un repo dans un état fixé par un commit donné (important), alors que le subtree permet de se référer à un repo ce qui simplifie le workflow si on souhaite juste consommer la dernière version de ce sous répo.

Workflow git subtree

Ajouter le subtree

Se positionner à l'intérieur du repo maitre puis ajouter le subtree avec un git subtree add :

git subtree add --prefix dossier-subtree git@github.com:behrouze/mon-super-repo-a-inclure.git master --squash

Cela va automatiquement cloner le repo souhaité dans dossier-subtree.

Pull du subtree

il suffit de rejouer la commande d'ajout en remplacant le git subtree add par git subtree pull :

git subtree pull --prefix dossier-subtree git@github.com:behrouze/mon-super-repo-a-inclure.git master --squash -m "subtree update"

Push du subtree

Si on souhaite apporter des modification au subtree, il est plus simple d'effectuer ces modifs dans le répo du subtree lui meme indépendament de cette arborescence, c'est à dire, le cloner dans un dossier a part entière et y effectuer les modifs.

Si malgré tout on souhaite gérer les 2 répos simultanément, il est possible de push des modifications faites dans le subtree, pour cela utiliser git subtree push sans l'option --prefix:

git subtree push --prefix dossier-subtree git@github.com:behrouze/mon-super-repo-a-inclure.git master

Workflow git submodule

Ajouter un submodule

git submodule add git@github.com:behrouze/mon-projet-de-sous-module.git

Clone d'un projet contenant un sous-module

Pour travailler avec les submodules, il faut cloner le répo parent avec l'option --recurse-submodules, dans l'exemple suivant

git clone --recurse-submodules git@github.com:behrouze/projet.git

Si on oublie l'option --recurse-submodules lors du git clone il est toujours possible de rattraper le coup avec :

cd dossier-du-sous-module
git submodule init
git submodule update

Pull du submodule

Le concepte a retenir, c'est que lorsqu'on initialise un submodule, on crée une sorte de pointeur vers un commit donné du submodule. Cela veut dire qu'un simple git pull ne mettra pas a jour le submodule 🥺

Si le repo du sous-module a été mis a jour et les commit pushés, il faut alors mettre à jour le submodule dans le projet qui l'embarque, et alors utiliser git submodule update:

git submodule update --remote
git commit -am "mise a jour du submodule"
git push

Suppression d'un submodule

Les 2 commandes suivantes permettent de supprimer complètement le submodule :

git submodule deinit dossier-du-sous-module # clean .git/config
git rm dossier-du-sous-module   # supprime le dossier et clean le .gitmodules