Domina Git Submodules en 9 comandos

De una duda en .NET Conf Zaragoza: cómo usar múltiples repos en uno. 9 comandos para dominar Git submodules: init/add/update/sync/status/set-branch/foreach

Durante mi charla sobre las novedades Aspire (https://blog.javivela.dev/p/novedades-en-aspire-131) en la .NET Conf 2025 Zaragoza uno de los asistentes (disculpa no recuerdo tu nombre) preguntó cómo poder organizar y hacer uso de varias aplicaciones almacenadas en varios repositorios desde otro repositorio. Una de las opciones que tenemos es Git Submodules.

En el siguiente articulo te explico 9 comandos para que domines Git Submodules.

¡Gracias por pasarte por aquí! 🙌
Si te interesa seguir recibiendo guías prácticas sobre Kubernetes, Azure, DevOps y contenedores directamente en tu email…
Suscríbete gratis y no te pierdas ninguna novedad. 🚀

Git submodules

Son repositorios Git anidados dentro de otros repositorios Git. Permiten incluir proyectos externos en tu proyecto o solución como un subdirectorio.

Un Git Submodule es esencialmente un puntero a un commit específico de otro repositorio Git.

¿Por qué usar Git Submodules?

• Reutilización de código: Compartir bibliotecas o componentes entre múltiples proyectos sin duplicar código

• Versionado preciso: Controlar exactamente qué versión de una dependencia usas

• Separación de concerns: Mantener módulos con ciclos de desarrollo independientes

• Colaboración multi-equipo: Diferentes equipos pueden trabajar en módulos separados con sus propios permisos

• Dependencias de terceros: Incluir librerías externas manteniendo la trazabilidad de versiones

¡Recuerda!

Revisa el contexto de tu solución, requisitos, ventajas y desventajas de la utilización de Git Submodules.

No son ideales para todo: si las dependencias cambian frecuentemente o requieren merges constantes, podrían complicar el workflow de tu día a día.

En esos casos, considera alternativas como paquetes (npm, pip) o Git subtrees.

9 Comandos para dominar Git Submodules

Activa uno o varios Git Submodules

Cuando clonas un repositorio con submodules, estos no están activos por defecto.

Usa init para registrarlos en tu configuración local antes de descargar su código.

git submodule init

Activar submodules específicos

git submodule init libs/utils
git submodule init libs/utils libs/auth

Añade un Git Submodule

git submodule add <url-repositorio> <ruta-destino>

Si quieres fijar una rama concreta desde el principio:

git submodule add -b main https://github.com/company/auth-lib.git libs/auth

Recuerda realizar commit con los cambios:

git commit -m “Añadir submodule utils”

Eliminar un Git Submodule

Desregistrar el Git Submodule

git submodule deinit -f libs/old-module
git rm -f libs/old-module
rm -rf .git/modules/libs/old-module     # opcional pero muy recomendado
git commit -m "Eliminar submodule old-module"

Clonar un repositorio con Git Submodules

Todo de una vez (opción recomendada):

git clone --recursive <url-repositorio>

Si ya clonaste sin --recursive:

git submodule update --init --recursive

Sincronizar contenido

Utiliza el comando git submodule update para sincronizar el contenido.

Actualizar TODOS los Git Submodules a su último commit remoto

git submodule update --remote --recursive

Actualizar UN Git Submodule específico:

git submodule update --remote libs/utils

Con merge o rebase automático:

git submodule update --remote --merge
git submodule update --remote --rebase

Después de actualizar, commitea el cambio de referencia:

git add .
git commit -m “Actualizar submodules a última versión”

Sincronizar URLs y configuración

Utiliza el comando sync en los siguientes supuestos:

1. La URL del repositorio remoto cambió

2. Cambias entre HTTPS y SSH

3. El repositorio se movió a otro servidor

4. Acabas de hacer git pull y .gitmodules tiene URLs nuevas

git submodule sync

Comprueba el estado de los Git Submodules

Ver estado básico de todos los Git Submodules

git submodule status

Ver resumen de cambios

git submodule summary

Ver status más detallado

git status

Configurar rama a seguir en un Git Submodule

Establece que el Git Submodules siga una rama específica (en vez de commit fijo). Actualiza .gitmodules.

git submodule set-branch -b develop libs/utils

Ejecuta comandos en todos los Git Submodules

git submodule foreach

Hacer pull en todos los Git Submodules

git submodule foreach 'git pull origin main'

Crear rama en todos los Git Submodules

git submodule foreach 'git checkout -b feature/update'

Si usas Git Submodules anidados, la opción--recursive recorrerá todo

git submodule foreach --recursive 'git status'

Limpiar TODO (cuidado – destructivo)

git submodule foreach --recursive 'git clean -fdx && git reset --hard'

Si este post te ha ayudado o aclarado algo, me harías muy feliz con un ❤️
Y si crees que le puede servir a alguien más… ¡compártelo! 🙌

Conclusión

Los Git Submodules son una herramienta poderosa cuando se usan con criterio, pero no son la solución mágica para todas las situaciones de dependencias. Valora bien el tradeoff entre control preciso vs. complejidad operativa.

Referencias

• https://git-scm.com/book/en/v2/Git-Tools-Submodules