Cómo añadir un repositorio Git como submódulo dentro de otro proyecto

Publicadas por

Cuando desarrollamos un proyecto grande, a veces necesitamos incluir otro repositorio Git dentro de nuestro código fuente. Por ejemplo, puede tratarse de una colección de diccionarios, una biblioteca de terceros, documentación compartida o cualquier otro componente que se mantenga de forma independiente.

Para estos casos, Git ofrece una característica llamada submódulos (submodules), que permite incluir un repositorio dentro de otro sin copiar ni duplicar su contenido.

¿Qué es un submódulo?

Un submódulo es una referencia a otro repositorio Git almacenada dentro de nuestro proyecto principal. De esta forma:

  • El proyecto principal mantiene una referencia a una revisión específica del repositorio externo.
  • El repositorio externo puede seguir desarrollándose de manera independiente.
  • No es necesario copiar archivos manualmente.
  • Se facilita la actualización de dependencias.

Estructura de ejemplo

Supongamos que tenemos el siguiente proyecto:

mi-proyecto/
├── src/
├── docs/
├── resources/
└── third-party/

Y queremos añadir un repositorio externo dentro de la carpeta third-party.

El resultado deseado sería:

mi-proyecto/
├── src/
├── docs/
├── resources/
└── third-party/
    └── mi-biblioteca/

Añadir el submódulo

Para agregar el repositorio, basta con ejecutar:

git submodule add https://github.com/usuario/mi-biblioteca.git third-party/mi-biblioteca

Git descargará el repositorio y creará automáticamente el archivo .gitmodules.

El archivo .gitmodules

Después de añadir el submódulo, Git genera una configuración similar a la siguiente:

[submodule "third-party/mi-biblioteca"]
    path = third-party/mi-biblioteca
    url = https://github.com/usuario/mi-biblioteca.git

Este archivo indica:

  • path: ubicación donde se encuentra el submódulo dentro del proyecto.
  • url: dirección del repositorio remoto.

Normalmente no es necesario editar este archivo manualmente.

Confirmar los cambios

Una vez agregado el submódulo, debemos registrar los cambios en Git:

git add .gitmodules third-party/mi-biblioteca
git commit -m "Add submodule"
git push

Clonar un proyecto que contiene submódulos

Si otra persona clona el proyecto utilizando:

git clone https://github.com/usuario/mi-proyecto.git

los submódulos no se descargarán automáticamente.

Para obtenerlos deberá ejecutar:

git submodule update --init --recursive

O bien realizar la clonación directamente con:

git clone --recursive https://github.com/usuario/mi-proyecto.git

Actualizar un submódulo

Para obtener los cambios más recientes del repositorio externo:

cd third-party/mi-biblioteca

git pull origin main

Luego, desde el proyecto principal:

git add third-party/mi-biblioteca
git commit -m "Update submodule"
git push

Eliminar un submódulo

Si ya no necesitamos el repositorio externo, podemos eliminarlo mediante:

git submodule deinit -f third-party/mi-biblioteca

git rm -f third-party/mi-biblioteca

rm -rf .git/modules/third-party/mi-biblioteca

Después se confirma el cambio:

git commit -m "Remove submodule"
git push

Recomendaciones

Una práctica habitual consiste en almacenar todas las dependencias externas dentro de una carpeta dedicada:

third-party/
external/
vendor/
deps/

Esto facilita:

  • Mantener organizado el proyecto.
  • Identificar rápidamente qué componentes pertenecen a terceros.
  • Simplificar la creación de paquetes para Linux, Windows y macOS.
  • Reducir la posibilidad de modificar accidentalmente código externo.

Dios les bendiga

Referencias

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

Git Submodule Documentation
https://git-scm.com/docs/git-submodule

Git Basics - Getting a Git Repository
https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository

GitHub Docs - Working with Submodules
https://docs.github.com/en/get-started/git-basics/about-git-submodules

GitHub Docs - Adding a Submodule to a Repository
https://docs.github.com/en/get-started/git-basics/about-git-submodules#adding-a-submodule

Atlassian Git Tutorials - Git Submodule
https://www.atlassian.com/git/tutorials/git-submodule

Pro Git Book (Second Edition)
https://git-scm.com/book/en/v2

Git Reference Manual
https://git-scm.com/docs

Comentarios

Publicar un comentario