Sinossi

git submodule add <url> <path>
git submodule update --init --recursive
git submodule foreach <cmd>

Descrizione

Il comando git submodule incorpora un repository Git esterno dentro un altro a un commit fisso. Il repo padre registra l'URL del submodule e lo SHA esatto da cui fare checkout, disaccoppiando le storie di padre e figlio. Questo è utile per il vendoring di librerie condivise o per comporre sistemi multi-repo.

I submodule sono potenti ma hanno una reputazione di confusione. Dopo aver clonato un progetto con submodule, devi eseguire git submodule update --init --recursive per popolarli. Aggiornare a un commit più recente del submodule è una danza in due passi: pull dentro il submodule, poi committa il nuovo SHA nel padre.

Nell'uso quotidiano, git submodule si integra con alias e CI.

Capire il modello dati di Git aiuta a prevedere i risultati.

Opzioni comuni

Esempi

git submodule add https://github.com/lib/foo.git vendor/foo
# Aggiunge un nuovo submodule a vendor/foo

git clone --recurse-submodules https://github.com/me/parent.git
# Clona con submodule in un passo

git submodule update --init --recursive
# Inizializza e popola tutti i submodule

git submodule foreach 'git pull origin main'
# Aggiorna ogni submodule alla punta del suo branch main

Errori comuni

Dimenticare --recurse-submodules al clone lascia directory submodule vuote. Pushare il repo padre senza prima pushare le modifiche del submodule lascia un riferimento penzolante per i collaboratori. Molti team passano a git subtree o monorepo per sfuggire alla complessità dei submodule.

Comandi correlati

git subtree, git clone --recurse-submodules, git config submodule