Submódulo de Git

Qué es un submódulo

Muy a menudo, un repositorio de código depende de código externo de otros repositorios. Puedes copiar y pegar directamente el código externo en el repositorio principal, o usar el sistema de gestión de paquetes de un lenguaje. Sin embargo, ambos métodos tienen la desventaja de no hacer seguimiento de los cambios en el repositorio externo. Git permite incluir otros repositorios Git llamados submódulos en un solo repositorio. Los submódulos permiten hacer seguimiento de cambios en varios repositorios desde un único repositorio padre. Los submódulos son repositorios incluidos en el repositorio padre en una ruta específica del directorio de trabajo. Pueden ubicarse en cualquier parte del directorio de trabajo y se configuran mediante el archivo .gitmodules, que se encuentra en la raíz del repositorio padre. El archivo .gitmodules contiene metadatos sobre la asignación entre la URL del proyecto del submódulo y el directorio local. Los submódulos admiten agregar, sincronizar, actualizar y clonar. Los submódulos solo rastrean commits específicos, no referencias ni ramas de Git.

Cuándo usar submódulos

Trabajar con submódulos es complicado, así que sugerimos algunos de sus mejores casos de uso.

• Si el subproyecto cambia demasiado rápido o los próximos cambios romperán la API, fija el código a un commit específico por seguridad.
• Si un componente no se actualiza con mucha frecuencia y quieres rastrearlo como una dependencia de proveedor.
• Si representas una parte del proyecto ante un tercero y quieres integrar su trabajo en un momento concreto (solo funciona cuando las actualizaciones no son demasiado frecuentes).
• Si el contexto tecnológico permite el empaquetado y la gestión formal de dependencias, deberías usar gestores de paquetes en lugar de submódulos.
• Si tu base de código es enorme y no quieres descargarla cada vez, usa submódulos para evitar que los colaboradores descarguen toda la base de código.

Comandos para submódulos de Git

Para crear un nuevo submódulo en el repositorio existente, usa git submodule add.

crear un nuevo submódulo en el repositorio existente git

mkdir git-submodule-demo
cd git-submodule-demo/
git init

Initialized empty Git repository in /Users/example/git-submodule-demo/.git/

Para agregar un submódulo al nuevo repositorio, ejecuta lo siguiente:

agregar submódulo al nuevo repositorio git

git submodule add https://somehost/example/textexample

Cloning into '/Users/example/git-submodule-demo/textexample'...
remote: Counting objects: 8, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 8 (delta 1), reused 0 (delta 0)
Unpacking objects: 100% (8/8), done.

El comando git submodule add toma una URL que apunta a un repositorio Git. Git clona inmediatamente el submódulo textexample. Comprueba el estado del repositorio ejecutando el comando git status:

comprobar el estado del repositorio git status

git status

On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

 new file: .gitmodules
 new file: textexample

Puedes confirmar los archivos en el repositorio usando los comandos git add y git commit:

confirmar los archivos git

git add .gitmodules textexample/
git commit -m "added submodule"

[master (root-commit) d5002d0] added submodule
 2 files changed, 4 insertions(+)
 create mode 100644 .gitmodules
 create mode 160000 textexample

Actualizar submódulos

Los miembros del equipo deben actualizar el código del submódulo si se ha modificado en otro lugar. No puedes usar git pull porque solo actualiza la referencia del repositorio padre al commit del submódulo, no el código real del submódulo. Para actualizar el submódulo al commit registrado, ejecuta:

actualizando el código del submódulo git

git submodule update

Nota: Sin la bandera --remote, este comando solo hace checkout del commit registrado en el repositorio padre y no obtiene los nuevos cambios del upstream.

Si se actualiza el archivo .gitmodules (por ejemplo, si cambia la URL del submódulo), ejecuta git submodule sync para actualizar .git/config local con las nuevas URL antes de ejecutar git submodule update.

Clonar submódulos de Git

Para clonar un proyecto con submódulos, usa el comando git clone. De forma predeterminada, clona el repositorio padre pero deja vacíos los directorios de los submódulos. Luego debes ejecutar git submodule init y git submodule update. El primero actualiza .git/config local con las asignaciones de .gitmodules, mientras que el segundo obtiene los datos del submódulo y hace checkout del commit registrado.

Como alternativa, usa la bandera --recursive con git clone para inicializar y actualizar automáticamente los submódulos. Si clonaste sin --recursive, ejecuta lo siguiente:

el comando git clone inicializa y actualiza submódulos

git clone /url/to/repo/with/submodules
git submodule init
git submodule update

Obtener el código del submódulo

Cuando haces pull de un repositorio que contiene nuevos submódulos, los demás miembros del equipo necesitan inicializarlos. Primero, ejecuta git pull para obtener el estado más reciente del repositorio padre. Si se enumeran nuevos submódulos, inicialízalos con:

iniciar nuevos submódulos git

git submodule init

Ten en cuenta que init solo actualiza el archivo local .git/config. Para obtener realmente el código y hacer checkout del commit registrado, debes ejecutar git submodule update.

Enviar actualizaciones en el submódulo

Como un submódulo es un repositorio independiente, puedes enviar cambios a él como a cualquier repositorio Git normal ejecutando comandos dentro del directorio del submódulo. Si haces nuevos commits dentro del submódulo, el repositorio padre seguirá apuntando al commit antiguo. Para actualizar el repositorio padre al nuevo commit, ejecuta git add en el directorio del submódulo, confirma y envía. Cuando ejecutas git status en el repositorio principal, el submódulo aparecerá como “Changes not staged for commit” con el mensaje “modified content (new commits)”. Esto indica que el código del submódulo está en un commit diferente del que espera el repositorio padre.

Los submódulos son una buena forma de mantener proyectos en repositorios separados y, al mismo tiempo, referenciarlos como carpetas en el directorio de trabajo de otro repositorio. Sin embargo, ten en cuenta que para muchos proyectos los submódulos no son la mejor práctica, y trabajar con ellos puede ser complicado.

Práctica

What are the key aspects of using Git submodules?

Git submodules allow including other repositories within a parent repository and tracking changes in several repositories via one repository.The command 'git submodule add' is used for copying and pasting external code into the main repository.The '.gitmodules' file contains metadata about the mapping between the submodule's URL and local directory.Submodules are updated automatically when the parent repository is updated using 'git pull'.To update the code of a submodule, the command 'git submodule update' should be used.Cloning a repository with submodules requires running 'git clone', followed by 'git submodule init' and 'git submodule update'.Changes made inside a submodule can be pushed directly from the submodule's directory.