Escenario

En algún momento de tu vida como desarrollador, puede darse el caso en el que estés desarrollando un proyecto formado por dos o más partes:

• Tu proyecto propiamente dicho
• Uno o varios proyectos compartidos, que forman parte de tu desarrollo, pero que también forman parte de otros proyectos

Esta situación, aunque pueda parecerlo, no es tan extraña.

Al modo tradicional, un developer *disciplinado* crearía un recurso local raíz del que colgaran tanto el repositorio principal como el secundario, de manera que las referencias al repositorio secundario desde el principal fuesen relativas a su raíz compartida.

Si usas git, tienes otra opción, un poco más limpia y sencilla de utilizar: Submodules.

Definición

Un Submodule es el mecanismo que ofrece git para clonar un repositorio secundario dentro de una carpeta de tu repositorio, de manera que puedas manejar (incluyendo la edición) el código de ambos repositorios por separado, pero que te permita referenciar desde el repositorio principal al secundario sin tener que ubicarlos en carpetas separadas.

Uso

Añadir un submodule a tu repositorio principal

Para añadir un submodule a tu repositorio, debes ejecutar la siguiente instrucción…

git submodule add <sub_repo> [<path>]

… donde el valor de sub_repo se corresponde con la url del repositorio secundario a añadir, y el valor de path, siendo opcional, permite decidir en qué carpeta se añadirá el submodule.

Una vez añadido un submodule, tendrás que añadir y «commitear» los cambios generados, que incluirán básicamente dos ficheros:

• Fichero .gitmodules
• Carpeta path o, por defecto, nombre del repositorio secundario.

Clonar un repositorio y sus submodules

Cuando un repositorio contiene uno o más submodules y lo clonas por primera vez, puedes hacerlo de manera que automáticamente se traiga el código de todos los submodules disponibles.

Para ello, ejecuta esto…

git clone --recurse-submodules <main_repo>

… donde main_repo se corresponde con la URL de tu repositorio principal.

Restaurar submodules

Puede ser que, bien por desconocimiento o por descuido, vayas a clonar un repositorio que contiene uno o varios submodules, y lo hagas simplemente con la siguiente instrucción.

git clone <main_repo>

xO Damn!

Un clonado estándar sólo se traerá aquellos ficheros que formen parte del repositorio principal, no de sus posibles submodules. Por tanto, de esos submodules, sólo se restaurarán las carpetas donde se ubicarían dichos submodules, pero no el contenido.

Para recuperar dicho contenido, primero ejecuta esta instrucción…

git submodule init

… para a continuación actualizar el contenido usando la siguiente instrucción:

git submodule update

Por defecto, esta última instrucción de git te recuperará el commit del proyecto secundario configurado en el momento de añadir el submodule (o de actualizarlo) en el proyecto principal.

Cambiar de commit en un submodule

¿Quieres usar otra commit? Por ejemplo, el último commit de una rama X… ¡Sin problema!

Imagina que estás en la rama `develop` de tu repositorio principal, y en el directorio raíz del repositorio.

Cambia a la carpeta donde se almacena tu submodule y haz `git status`. Te dirá en qué rama estás, si tienes cambios pendientes… ¡Cambia de rama!

git checkout <otra_rama>

Nota: intenta que el valor de otra_rama no sea develop para este ejemplo.

¿Tienes muchos submodules? ¡Sin problema!

git submodule foreach "git checkout <otra_rama>"

Vuelve a hacer `git status`. Estás en la nueva rama (si no ha habido errores). Retrocede un nivel con `cd ..` y haz `git status`. En esta ocasión, la rama indicada en `git status` será `develop`. Esto es debido a que en realidad, en función de en qué carpeta te encuentres, estás en repositorios distintos.

Referencias

Si quieres ahondar en el tema de los submodules, mi primera recomendación sería que visitases la documentación oficial de Git-Scm, donde encontrarás toda la información de este artículo, además de información adicional de cómo utilizar los submodules para actualizar el repositorio secundario.