Cosa sono i submodule

Un submodule e un repository Git annidato dentro un altro. Il repository padre registra l'URL del submodule e uno SHA di commit specifico, cosi chi clona il padre puo recuperare esattamente il codice testato insieme.

Aggiungere un submodule

git submodule add https://github.com/example/lib third_party/lib
git commit -m "Add lib submodule"

Clonare un progetto con submodule

git clone --recurse-submodules https://github.com/you/parent
git submodule update --init --recursive

Impostare submodule.recurse = true globalmente.

Aggiornare a un nuovo commit del submodule

cd third_party/lib
git fetch
git checkout v2.0.0
cd ../..
git add third_party/lib
git commit -m "Bump lib to v2.0.0"

Diff e status

git diff --submodule=log
git submodule status
git submodule summary

Foreach

git submodule foreach 'git fetch --all'
git submodule foreach --recursive 'git checkout main && git pull'

Errori comuni

Dimenticare --init al primo clone lascia le directory dei submodule vuote. Modificare dentro un submodule e committare nel padre senza fare push prima del submodule lascia i collaboratori con un padre che fa riferimento a uno SHA irraggiungibile.

Insidia del branch tracking

I submodule fanno checkout su detached HEAD allo SHA registrato. Le modifiche li non sono su un branch per default. Prima di cambiare i file, fare git checkout di un branch dentro il submodule.