Lista de frustraciones

Los submódulos son potentes pero hacen tropezar a los nuevos usuarios repetidamente. Esta página cataloga los fallos más comunes y las recetas que los arreglan.

Directorio de submódulo vacío

git submodule update --init --recursive

Ediciones en HEAD desacoplado perdidas

Editaste dentro de un submódulo, hiciste commit, luego ejecutaste git submodule update en el padre. La actualización reseteó el submódulo al SHA registrado, abandonando tu trabajo en HEAD desacoplado. Recupera con git reflog dentro del submódulo.

cd third_party/lib
git reflog
git checkout -b rescue HEAD@{1}

Crea siempre una rama dentro de un submódulo antes de editar.

URL cambiada upstream

git submodule sync --recursive
git submodule update --init --recursive

Eliminar un submódulo

git submodule deinit -f third_party/lib
git rm -f third_party/lib
rm -rf .git/modules/third_party/lib
git commit -m "Eliminar submódulo lib"

Contenido modificado pero sin diff

git submodule update --recursive
# o
git add third_party/lib && git commit -m "Subir lib"

El orden de push importa

git config --global push.recurseSubmodules on-demand

Submódulos shallow

git submodule update --init --recursive --depth 1

Errores comunes

Tratar a los submódulos como subdirectorios normales — no lo son, todo comando Git se detiene en el límite a menos que pases --recurse-submodules. Mezclar submódulos con seguimiento de rama con flujos de SHA fijo lleva a confusión.