Ha pasado lo que era previsible. Ana lleva meses extrayendo piezas reutilizables de gestor-tareas: el botón con estado de carga, el diálogo de confirmación, el campo de texto con validación. Al principio vivían en app.js; después en un componentes.js aparte. Y ahora hay dos proyectos más en la empresa que quieren usarlos.

El equipo ha hecho lo correcto: ha creado un repositorio propio, componentes-ui, en git.ejemplo.es/equipo/componentes-ui.git, con su propio historial, sus propias versiones etiquetadas y sus propios responsables.

Y ahora surge la pregunta incómoda: ¿cómo usa gestor-tareas esa biblioteca?

Copiar los ficheros y pegarlos funciona hasta el primer arreglo, momento en el que hay tres copias divergentes. Y no basta con "tener la biblioteca en algún sitio": hace falta que quede registrado qué versión exacta de componentes-ui usa cada commit de gestor-tareas, para que al hacer git checkout v1.0.0 dentro de seis meses se pueda reconstruir exactamente aquella aplicación.

La respuesta nativa de Git a ese problema son los submódulos. Son potentes, son la solución correcta para ciertos casos, y tienen fama —merecida— de morder a quien no entiende cómo funcionan. Esta lección va de entenderlos bien.

1. Qué es exactamente un submódulo
2. git submodule add: añadir componentes-ui
3. Qué se confirma exactamente: el objeto de tipo commit
4. Clonar un proyecto con submódulos
5. Actualizar: el submódulo frente al puntero
6. Trabajar dentro de un submódulo y el detached HEAD
7. Inspección: status, foreach y diff --submodule
8. submodule.recurse y otras opciones que quitan dolor
9. Los problemas reales
10. Alternativas: submódulos, subtree, paquetes y monorepo

La definición completa, y todo lo demás se deduce de ella:

Un submódulo es una entrada en el árbol del repositorio padre que apunta a un commit concreto de otro repositorio, más una línea en el fichero .gitmodules que dice de dónde clonar ese otro repositorio.

Dos piezas, ninguna más:

1. El puntero: una entrada en el árbol (lección 01-04) cuyo tipo no es blob ni tree, sino commit. Guarda un hash de 40 caracteres y nada más.
2. .gitmodules: un fichero de texto versionado, en la raíz del padre, que asocia cada ruta con su URL.

Lo crucial: el repositorio padre no contiene el código de la biblioteca. Contiene un post-it que dice "aquí va componentes-ui, exactamente en el commit 7f3a9d2". El código vive en el otro repositorio, con su propio .git, su propio historial y sus propias ramas.

De ahí salen las tres propiedades que definen la experiencia de trabajar con submódulos:

• Reproducibilidad exacta. Cada commit de gestor-tareas fija una versión concreta de la biblioteca. git checkout v1.0.0 + actualizar submódulos reconstruye la aplicación tal cual era.
• Historiales independientes. Un commit en la biblioteca no aparece en el historial de la aplicación. Son dos repositorios distintos con dos git log distintos.
• Actualización explícita. El puntero no se mueve solo. Si la biblioteca avanza, el padre sigue apuntando al mismo commit hasta que alguien decida moverlo y lo confirme.

Esa última propiedad es simultáneamente la mayor virtud y la mayor fuente de quejas.

Ana lo hace desde la raíz de gestor-tareas:

Sintaxis:

• Si omites la ruta, se usa el nombre del repositorio (componentes-ui/).
• -b <rama> registra una rama de seguimiento, útil para --remote (apartado 5).

Lo que ha pasado, exactamente:

Dos ficheros nuevos, no doscientos. El directorio entero de la biblioteca aparece como una sola entrada. Ese es el primer indicio visible de que no se está guardando el contenido.

El .gitmodules generado:

Y el commit:

Fíjate en la última línea: create mode 160000. Los modos que conocíamos de la lección 01-04 eran 100644 (fichero normal), 100755 (ejecutable) y 040000 (directorio). 160000 es el modo especial de un submódulo, y ese número es literalmente cómo Git marca "aquí hay un puntero a un commit externo".

Ana ya puede usarlo desde index.html:

Y envía:

Vale la pena verlo por dentro, porque entenderlo aquí evita toda la confusión posterior. Retomamos las herramientas de la lección 01-04:

Ahí está. El árbol vendor contiene una entrada de tipo commit con modo 160000. No es un tree, no es un blob: es una referencia a un objeto commit que ni siquiera está en la base de datos de objetos de gestor-tareas.

Efectivamente: ese objeto vive en el repositorio de componentes-ui, no aquí. El padre solo guarda su nombre.

Y el tamaño total que ocupa esa referencia en el repositorio padre:

Un árbol con una entrada: unas decenas de bytes. El repositorio de gestor-tareas no ha crecido nada por incorporar una biblioteca de 200 commits.

De aquí se deduce por qué el diff de un cambio de submódulo tiene ese aspecto tan raro:

Una línea que cambia. Todo el contenido de la biblioteca puede haber cambiado, pero para el padre esto es un puntero que se mueve.

Bruno clona el proyecto por primera vez:

El directorio existe pero está vacío. Este es el primer tropiezo clásico, y le pasa a todo el mundo: git clone no descarga los submódulos por defecto.

Hay dos formas de arreglarlo.

Clona el padre y, acto seguido, inicializa y clona cada submódulo en el commit fijado.

O en un solo comando:

La separación en dos pasos tiene sentido cuando la entiendes:

El paso de init existe porque permite cambiar la URL localmente antes de clonar (por ejemplo, para usar un espejo interno o HTTPS en vez de SSH) sin tocar el .gitmodules que comparte todo el equipo:

También se puede inicializar solo alguno, en proyectos con muchos:

Aquí está la distinción que más confusión genera, y merece un encabezado propio.

Hay dos actualizaciones distintas y hacen cosas opuestas:

Es el caso normal, y el que se ejecuta después de un git pull:

Ana ha subido un commit que mueve el puntero de la biblioteca. Bruno hace git pull del padre, y submodule update deja su copia de componentes-ui exactamente en el commit que Ana fijó. Sincronización, no actualización.

Git ha hecho fetch en el submódulo y ha hecho checkout de la punta de su rama de seguimiento. ¿Qué rama? Por este orden:

1. La indicada en .gitmodules con branch = <rama> (o git submodule add -b).
2. Si no hay ninguna, HEAD del remoto, que suele ser main.

Y ahora lo importante: eso todavía no ha cambiado nada en el historial del padre. Es un cambio sin confirmar:

(new commits) significa: "el submódulo está en un commit distinto del que yo tengo registrado". Para que la actualización sea real y le llegue al resto del equipo, hay que confirmarla en el padre:

La regla que resume todo el apartado: actualizar el submódulo es un cambio en tu disco; actualizar el puntero es un commit en el padre. Si no confirmas, nadie más ve la actualización, y el siguiente git submodule update te la deshace.

Carla necesita arreglar el diálogo de confirmación, que está en la biblioteca. Entra al directorio del submódulo:

Detached HEAD, el estado de la lección 03-02. Y tiene toda la lógica del mundo: el padre no dice "usa la rama main de la biblioteca", dice "usa el commit 7f3a9d2". Git hace exactamente eso, y un checkout de un commit suelto deja HEAD desacoplado.

Consecuencia peligrosa: si Carla edita y confirma aquí sin más, crea un commit que no pertenece a ninguna rama. En cuanto alguien haga git submodule update, ese commit queda huérfano y solo se recupera por el reflog (lección 09-04).

El procedimiento correcto tiene cuatro pasos:

El paso 3 es el que se olvida, y su omisión es el fallo más grave de todos los submódulos. Si Carla confirma el puntero en el padre sin haber publicado el commit del submódulo, el resultado es:

El padre apunta a un commit que no existe en ningún sitio salvo en el disco de Carla. El proyecto está roto para todo el equipo hasta que ella publique.

Git tiene una red de seguridad para esto, y hay que activarla:

check es la opción recomendada: te avisa y te obliga a decidir, en lugar de publicar cosas por su cuenta.

El primer carácter es un indicador de estado, y hay que saber leerlo:

Ejemplos de las situaciones problemáticas:

→ Bruno acaba de clonar sin --recurse-submodules.

→ Alguien ha movido el submódulo y no lo ha confirmado en el padre.

Con --recursive baja por los submódulos anidados.

Ejecuta un comando en cada submódulo:

Dentro del comando, Git define variables útiles:

Por defecto, un cambio de submódulo se ve como aquella línea de Subproject commit. --submodule=log muestra los commits que hay de diferencia, que es infinitamente más informativo:

Tres commits de diferencia, con sus asuntos. Los modos disponibles:

Y como es lo que se quiere casi siempre, conviene fijarlo:

Con status.submoduleSummary, git status también resume los commits pendientes en lugar de decir solo (new commits).

La mayor parte del sufrimiento con submódulos viene de olvidar el --recurse-submodules en algún comando. Esta opción lo activa por defecto para casi todos:

A partir de ahí, git pull, git switch, git checkout, git reset y otros actualizan los submódulos automáticamente. Es la primera configuración que debería poner cualquiera que trabaje con submódulos.

Nota: submodule.recurse no afecta a git clone, que sigue necesitando su --recurse-submodules explícito.

El juego completo de configuración recomendada:

Y un puñado de comandos que resuelven situaciones concretas:

Ese último merece explicación: deinit lo desregistra, git rm quita la entrada del árbol y la línea de .gitmodules, y el rm -rf de .git/modules/ borra el repositorio interno que Git conserva (desde la versión 1.7.8, el .git del submódulo no está dentro de su directorio, sino en .git/modules/<nombre> del padre, y en el directorio del submódulo queda un fichero .git que apunta allí — la misma técnica que veremos con worktree en la lección 06-06).

Todo lo anterior funciona. Estos son los tropiezos que se dan en la práctica y su solución.

Síntoma. Alguien clona y vendor/componentes-ui/ no tiene nada. La aplicación no arranca.

Causa. git clone sin --recurse-submodules.

Solución. git submodule update --init --recursive. Y prevención: documentarlo en el README.md, y —mejor todavía— un hook post-checkout de la lección 06-01 que avise:

Ya visto en el apartado 6: alguien confirmó el puntero sin publicar el commit del submódulo.

Solución. Que esa persona haga git push en el submódulo. Prevención: push.recurseSubmodules check.

Síntoma. git status en el padre dice modified: vendor/componentes-ui (modified content) y no hay forma de que desaparezca.

Causa. Alguien ha editado ficheros dentro del submódulo sin confirmarlos allí.

Solución, según lo que quieras:

La opción ignore acepta none (por defecto), untracked (ignora ficheros sin seguimiento), dirty (ignora también las modificaciones) y all (ignora incluso un puntero distinto). all es peligroso: oculta exactamente la información que necesitas ver.

Síntoma. Carla pasa de una rama que tiene el submódulo a otra que no lo tiene (o que lo tiene en otra versión), y aparecen ficheros extraños o el directorio se queda con contenido antiguo.

Causa. El checkout del padre mueve el puntero, pero el contenido del directorio del submódulo no se actualiza solo salvo que lo pidas.

Solución. submodule.recurse true, o acordarse de git checkout --recurse-submodules <rama>.

Y un caso especialmente molesto: al volver a una rama anterior a la incorporación del submódulo, el directorio queda ahí con contenido y sin seguimiento. No es un fallo: es que Git no borra directorios que contienen un repositorio para no destruir trabajo.

Dos ramas actualizan el submódulo a commits distintos:

No hay marcadores de conflicto que editar: el conflicto es qué hash debe ganar. La resolución consiste en decidir el commit correcto:

A menudo la respuesta correcta no es ninguno de los dos, sino un commit posterior del submódulo que contiene los cambios de ambas ramas. Fusiónalos primero dentro del submódulo, y después apunta ahí.

Y el problema del que menos se habla: los submódulos añaden un paso a todo. Cada pull puede necesitar un submodule update; cada cambio en la biblioteca son dos commits y dos push; cada persona nueva se equivoca al clonar la primera vez. Nada de eso es grave por separado, pero se acumula.

Por eso la pregunta importante no es "¿cómo se usan los submódulos?", sino "¿es esta la herramienta adecuada para mi caso?". Vamos con ello.

Hay cuatro formas razonables de componer un proyecto a partir de varias piezas.

Un párrafo por cada una:

git subtree hace lo contrario que los submódulos: copia el contenido de la biblioteca dentro del padre y lo mantiene sincronizado con fusiones. Quien clona no tiene que hacer nada especial, porque el código está ahí. A cambio, el repositorio crece, el historial se mezcla y contribuir de vuelta a la biblioteca es incómodo. Es una buena opción cuando consumes una dependencia y rara vez la modificas, y cuando la fricción del --recurse-submodules es inaceptable (por ejemplo, si el proyecto lo clona gente ajena al equipo). Los comandos básicos son git subtree add, pull y push; no lo desarrollamos aquí porque merecería su propia lección.

Un gestor de paquetes (npm, pip, Maven, Cargo...) es, en la mayoría de los proyectos modernos, la respuesta correcta. Si componentes-ui se puede publicar como paquete —aunque sea en un registro privado de la empresa—, el equipo declara "@equipo/componentes-ui": "^2.1.0" en su package.json, el fichero de bloqueo garantiza la reproducibilidad, y toda la maquinaria de versiones semánticas (lección 05-05) trabaja a su favor. Que Git pueda hacer esto no significa que deba. Antes de elegir submódulos, pregúntate siempre si un paquete resolvería el problema.

El monorepo —un único repositorio con la aplicación y la biblioteca dentro— elimina el problema de raíz: un commit puede cambiar ambas a la vez, y siempre son coherentes. Es lo que hacen muchas empresas grandes. El precio es un repositorio que crece mucho y necesita herramientas propias para permisos, compilaciones parciales y rendimiento. Ese escenario, con sus técnicas —clones parciales, sparse-checkout, clones superficiales—, es el tema de la lección 10-04: Escalando Git para Proyectos Grandes.

Los submódulos ganan cuando se cumplen a la vez varias de estas condiciones:

• La dependencia es código fuente que compilas junto al tuyo, no un artefacto publicable.
• Necesitas fijar un commit exacto, no un rango de versiones.
• Modificas la biblioteca con cierta frecuencia y quieres que sea un repositorio de primera clase.
• No hay (o no quieres montar) un registro de paquetes interno.
• El equipo es pequeño y se puede formar en la mecánica.

Casos reales típicos: temas y plugins de un CMS, bibliotecas C/C++ compiladas desde fuente, configuraciones compartidas entre proyectos, firmware con componentes de terceros.

Y una mención que hay que hacer aquí porque a veces se confunde: si tu problema no es código compartido sino ficheros grandes y binarios —imágenes de alta resolución, vídeos, modelos, ejecutables— la respuesta no es ninguna de las cuatro, sino Git LFS, que sustituye esos ficheros por punteros de texto y guarda el contenido en un almacén aparte. Es el tema de la lección 10-03: Git LFS para Ficheros Grandes.

Para gestor-tareas, el equipo acaba tomando esta decisión: submódulo por ahora, porque componentes-ui está en pleno desarrollo, se modifica cada semana y no compensa publicar un paquete a cada cambio. Cuando la biblioteca se estabilice y otros equipos empiecen a consumirla, pasarán a publicarla en el registro npm interno. Es una decisión sensata: la forma de componer un proyecto puede cambiar con su madurez.

Error 1: clonar sin --recurse-submodules. El error número uno. Directorio vacío y aplicación rota. Solución: git submodule update --init --recursive.

Error 2: confirmar el puntero sin publicar el commit del submódulo. Rompe el proyecto para todos los demás. Prevención: git config push.recurseSubmodules check.

Error 3: trabajar en el submódulo sin salir del detached HEAD. Los commits quedan huérfanos. Haz git switch <rama> antes de tocar nada.

Error 4: confundir submodule update con submodule update --remote. El primero obedece al padre; el segundo trae lo nuevo del remoto. Son opuestos.

Error 5: olvidar confirmar en el padre tras actualizar. Si no hay commit en el padre, la actualización solo existe en tu disco.

Error 6: usar submodule.<n>.ignore = all. Oculta precisamente la información que necesitas ver. Como mucho, dirty.

Error 7: intentar borrar un submódulo con rm -rf. Deja restos en .git/config, .gitmodules y .git/modules/. Usa la secuencia deinit + git rm.

Error 8: elegir submódulos por defecto. Casi siempre hay una alternativa más simple. Justifica la elección.

Consejo 1: git config --global submodule.recurse true, siempre. Es la configuración que más dolor evita.

Consejo 2: diff.submodule log y status.submoduleSummary true. Convierten hashes ilegibles en listas de commits.

Consejo 3: apunta a commits estables, preferiblemente etiquetados. Un submódulo apuntando a la punta de main de otro equipo es una fuente inagotable de sorpresas. git describe --tags dentro del submódulo te dice dónde estás.

Consejo 4: documenta la mecánica en el README.md. Cinco líneas con el clone --recurse-submodules y el submodule update --init ahorran una hora a cada persona nueva.

Consejo 5: un hook post-checkout que avise de submódulos sin inicializar. Es el uso perfecto de lo aprendido en la lección 06-01.

Consejo 6: al actualizar el puntero, explica por qué en el mensaje. "Actualizar componentes-ui" no dice nada; "Actualizar componentes-ui a v2.2.0 por la corrección del foco" convierte ese commit en información útil.

Trabajando en local (sin servidor remoto):

1. Crea un repositorio biblioteca con tres commits y una etiqueta v1.0.
2. Crea un repositorio aplicacion con dos commits.
3. Añade biblioteca como submódulo de aplicacion en vendor/biblioteca y confírmalo.
4. Inspecciona el árbol con git cat-file -p HEAD^{tree} y localiza la entrada de modo 160000.
5. Comprueba que el objeto commit al que apunta no existe en la base de objetos del padre.

Sobre el ejercicio anterior:

1. Añade dos commits nuevos a biblioteca.
2. En aplicacion, comprueba que git status no dice nada (el puntero sigue igual).
3. Ejecuta git submodule update --remote y observa qué cambia en git status.
4. Confirma el nuevo puntero con un mensaje que explique el porqué.
5. Comprueba el diff del puntero con --submodule=short, --submodule=log y --submodule=diff.

1. Clona aplicacion sin --recurse-submodules y comprueba el directorio vacío y la salida de git submodule status.
2. Arréglalo con git submodule update --init.
3. En el clon, entra al submódulo y comprueba que estás en detached HEAD. Haz un commit ahí sin cambiar de rama y observa el aviso de Git.
4. Recupera ese commit huérfano poniéndolo en una rama.
5. Elimina el submódulo del padre por completo (deinit, git rm, .git/modules/) y verifica que no quedan restos.

Solución 1:

La opción -c protocol.file.allow=always hace falta desde Git 2.38 para usar submódulos con rutas locales; con URLs https:// o git@ no es necesaria.

Ahí está el modo 160000 y el tipo commit.

Confirmado: el objeto no está en la base de datos del padre. Solo se guarda su nombre.

Solución 2:

El padre sigue apuntando al commit fijado: los commits nuevos de la biblioteca le son indiferentes. Esa es la propiedad, no un fallo.

Mucho más útil: dos commits, con sus asuntos.

Muestra el contenido real de los cambios dentro del submódulo.

Prefijo espacio: todo en orden.

Solución 3:

El - inicial es el diagnóstico: no inicializado.

El + avisa: el submódulo está en un commit distinto del registrado. Y ese commit no está en ninguna rama:

Ya está a salvo. Sin ese paso, un git submodule update lo habría dejado huérfano.

Los tres sitios donde vive un submódulo, limpios. Un rm -rf a secas habría dejado restos en los tres.

Los submódulos son la respuesta nativa de Git a componer un proyecto con varios repositorios, y su comportamiento entero se deduce de una sola idea. Lo esencial:

• Un submódulo es un puntero a un commit concreto de otro repositorio, guardado como una entrada de árbol de modo 160000 y tipo commit, más una línea en .gitmodules. El padre no contiene el código de la biblioteca.
• Eso da reproducibilidad exacta (cada commit del padre fija una versión de la dependencia), historiales independientes y actualización explícita: el puntero no se mueve solo.
• git submodule add <url> <ruta> lo incorpora; el commit resultante toca dos ficheros, no doscientos.
• Clonar requiere --recurse-submodules, o git submodule update --init --recursive después. Es el error más frecuente.
• Hay dos actualizaciones opuestas: submodule update pone el submódulo donde dice el padre; submodule update --remote trae lo nuevo del remoto y hay que confirmar el puntero en el padre para que exista de verdad.
• Dentro del submódulo se está en detached HEAD: cambia a una rama antes de trabajar, y publica el commit del submódulo antes de confirmar el puntero (push.recurseSubmodules check).
• git submodule status con sus prefijos ( , -, +, U), foreach y diff --submodule=log son las herramientas de inspección. submodule.recurse true, diff.submodule log y status.submoduleSummary true eliminan la mayor parte de la fricción.
• Los problemas reales son siempre los mismos: directorios vacíos, punteros a commits sin publicar, cambios sin confirmar dentro del submódulo, cambios de rama en el padre y conflictos de puntero. Todos tienen solución conocida y todos tienen prevención.
• Y sobre todo: no son la opción por defecto. Compáralos con git subtree, con un gestor de paquetes (a menudo la mejor respuesta) y con el monorepo (lección 10-04), y elige con criterio. Para binarios grandes, la herramienta es Git LFS (lección 10-03).

gestor-tareas ya se compone de dos repositorios, y el equipo tiene la trazabilidad que necesitaba. Pero queda un problema pendiente desde el final del módulo 5, y es el de Carla.

Carla trabaja en funcionalidad/borrado-multiple, una rama larga y a medias. Cada vez que llega un aviso urgente —un fallo en producción, una revisión de código que atender, una duda sobre otra rama— tiene que hacer git stash, cambiar de rama, resolver, volver y git stash pop. Diez veces al día. Y con el submódulo recién añadido la cosa empeora, porque cada cambio de rama arrastra también su actualización.

Su primera idea es clonar el repositorio dos veces. Funcionaría, pero duplica el espacio, duplica los fetch y deja dos repositorios con historiales que hay que mantener sincronizados a mano. Hay una solución mucho mejor, integrada en Git y sorprendentemente poco conocida: varios directorios de trabajo compartiendo una única base de datos de objetos. Es la lección 06-06: Múltiples Copias de Trabajo con git worktree.