Sinopsis
git submodule add <url> <path>
git submodule update --init --recursive
git submodule foreach <cmd>Descripción
El comando git submodule gestiona repositorios Git anidados dentro de un repositorio padre. Cada submódulo es un commit fijado de otro repo, lo que te permite incluir dependencias o componentes externos como parte de tu proyecto.
Los submódulos son notoriamente complicados: requieren init y update explícitos tras un clone, los commits del submódulo no son visibles en el log del padre, y los pushes a submódulos son una operación separada. Considera alternativas (git subtree, gestores de paquetes) antes de adoptarlos.
En el uso diario, este comando se integra estrechamente con alias de shell, plugins de editor e integración continua. Los usuarios avanzados a menudo añaden alias que combinan los flags que siempre pasan. El formato de salida puede personalizarse vía configuración de Git. Cuando algo sale mal, ejecuta el comando con GIT_TRACE=1 para revelar las llamadas plumbing subyacentes.
Entender cómo este comando interactúa con el resto del modelo de datos de Git rinde dividendos. Cada comando opera sobre algún subconjunto de las piezas (objetos, index, refs, árbol de trabajo), y saber cuáles toca ayuda a predecir resultados y a recuperarse de errores.
Opciones comunes
| Subcomando | Descripción |
|---|---|
add <url> <path> | Add a new submodule. |
init | Register submodule URLs in .git/config. |
update --init | Init and check out submodules. |
update --recursive | Recurse into nested submodules. |
update --remote | Update to the upstream branch tip. |
foreach <cmd> | Run a command in every submodule. |
deinit <path> | Remove a submodule from the working tree. |
Ejemplos
git submodule add https://github.com/lib/foo.git vendor/foo
# Add a new submodule at vendor/foo
git clone --recurse-submodules https://github.com/me/parent.git
# Clone with submodules in one step
git submodule update --init --recursive
# Initialize and populate all submodules
git submodule foreach 'git pull origin main'
# Update each submodule to its main branch tipErrores comunes
Forgetting --recurse-submodules on clone leaves empty submodule directories. Pushing the parent repo without first pushing submodule changes leaves a dangling reference for collaborators. Many teams move to git subtree or monorepos to escape submodule complexity.
Comandos relacionados
git subtree, git clone --recurse-submodules, git config submodule