Usando submodules en git

Los submodules de git permiten incluir un repositorio en otro en cualquier ubicación. Incluir por ejemplo una librería de javascript en un proyecto web como un módulo permite funcionar con su última versión fácilmente, sin necesidad de preocuparse por sustituir versiones manualmente: basta actualizar el repositorio.

Yo he usado los módulos de git por primera vez para hacer una web con Hugo. En el repositorio del sitio web he incluido el theme Learn de Hugo como módulo.

Añadir un módulo a un repositorio

skotperez@lee:~/project$ git submodule add https://github.com/matcornic/hugo-theme-learn themes/learn

Dos parámetros para añadir un módulo a un repositorio:

• La URL del repositorio que se quiere añadir. En el ejemplo https://github.com/matcornic/hugo-theme-learn.
• La ubicación en el repositorio principal donde se quiere incluir y tener disponible el módulo. El el ejemplo themes/learn.

Al añadir el primer módulo se crea en el repositorio principal el archivo .gitmodules, en el que se listan todos los módulos que se han añadido.

skotperez@lee:~/project$ cat .gitmodules
[submodule "themes/learn"]
        path = themes/learn
        url = https://github.com/matcornic/hugo-theme-learn.git

Añadir un módulo es un cambio como cualquier otro y hay que hacer commit y subirlo al repositorio remoto de la manera habitual.

Clonando un repositorio con submodules

Cuando se clona un repositorio con submodules, las ubicaciones que contienen los módulos aparecerán vacías. Para poder usar los repositorios de los módulos primero hay que activarlos y descargar su contenido:

skotperez@lee:~/project$ git submodule init
skotperez@lee:~/project$ git submodule update

Eliminar un módulo

No existe un comando de git para eliminar un módulo. Se puede eliminar un módulo de un repositorio de la siguiente manera:

1. Eliminar la información sobre el módulo en el archivo .gitmodules.
2. Eliminar la información sobre el módulo en el archivo .git/config.
3. Eliminar la ubicación asociada al módulo. En el ejemplo git rm --cached themes/learn.

Actualizar un módulo

Añadir un repositorio como módulo a otro se está añadiendo su última versión. Si después de añadirlo hay algún cambio en el repositorio incluido como módulo no se reflejará en nuestro repositorio. Para actualizar el módulo a su última versión hay que situarse en la ubicación asociada al módulo y comprobar en qué rama está el submodule. Si no tiene rama asociada la asociamos y por último descargamos la última versión con git pull:

skotperez@lee:~/project$ cd themes/learn
skotperez@lee:~/project/themes/learn$ git status
# Not currently on any branch.
nothing to commit (working directory clean)
skotperez@lee:~/project/themes/learn$git checkout master
skotperez@lee:~/project/themes/learn$git pull
remote: Enumerating objects: 109, done.
remote: Counting objects: 100% (109/109), done.
remote: Compressing objects: 100% (7/7), done.
remote: Total 303 (delta 102), reused 104 (delta 102), pack-reused 194
Recibiendo objetos: 100% (303/303), 1.92 MiB | 1.04 MiB/s, listo.
Resolviendo deltas: 100% (162/162), completado con 54 objetos locales.
Desde https://github.com/matcornic/hugo-theme-learn
   59c4cbf..9ed9958  master     -> origin/master
 * [nuevo tag]       2.1.0      -> 2.1.0
Actualizando 59c4cbf..9ed9958
Fast-forward
...

Luego solo queda añadir los cambios a stage, declararlos con un commit y subirlos al repositorio remoto.

Esta pequeña guía está muy inspirada en la que publicó Chris Jean en su blog: Git Submodules: Adding, Using, Removing, Updating.