Qué son los submódulos

Un submódulo es un repositorio Git anidado dentro de otro. El repo padre registra la URL del submódulo y un SHA específico, así cualquiera que clone el padre puede obtener el código exacto que se probó conjuntamente. Usa submódulos cuando quieras anclar una dependencia a un commit fijo preservando su historia independiente.

Añadir un submódulo

git submodule add https://github.com/example/lib third_party/lib
git commit -m "Añadir submódulo lib"

Esto crea un archivo .gitmodules que registra la ruta y la URL.

Clonar un proyecto con submódulos

git clone --recurse-submodules https://github.com/you/parent
# o, tras un clone simple:
git submodule update --init --recursive

Configura submodule.recurse = true globalmente para que comandos como git pull y git checkout actualicen submódulos automáticamente.

Actualizar a un nuevo commit del submódulo

cd third_party/lib
git fetch
git checkout v2.0.0
cd ../..
git add third_party/lib
git commit -m "Subir lib a v2.0.0"

Diff y 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'

Errores comunes

Olvidar --init en el primer clone deja directorios de submódulo vacíos. Editar dentro de un submódulo y hacer commit en el padre sin haber hecho push del submódulo primero deja a los colaboradores con un padre que referencia un SHA inalcanzable. Siempre haz push del submódulo primero, luego del padre. Configura push.recurseSubmodules = on-demand.

Trampa de seguimiento de rama

Los submódulos hacen checkout de un HEAD desacoplado en el SHA registrado. Antes de cambiar archivos, haz git checkout de una rama dentro del submódulo.