7.11 Herramientas de Git - Submódulos

El modelo más simple de usar submódulos en un proyecto sería si simplemente consumiera un subproyecto y quisiera obtener actualizaciones de él de vez en cuando, pero en realidad no estuviera modificando nada en el proceso. Veamos un ejemplo simple de esto.

Si desea buscar trabajo nuevo en un submódulo, puede acceder al directorio y ejecutar git fetch y git merge en la rama upstream para actualizar el código local.

Ahora, si vuelve al proyecto principal y ejecuta git diff --submodule puede ver que el submódulo se actualizó y obtener una lista de commits que se le agregaron. Si no desea escribir --submodule cada vez que ejecuta git diff, puede establecerlo como el formato predeterminado configurando el valor de configuración diff.submodule en “log”.

Si hace “commit” en este punto, bloqueará el submódulo para que tenga el nuevo código cuando otras personas lo actualicen.

También hay una forma más sencilla de hacer esto si prefiere no buscar y fusionar manualmente en el subdirectorio. Si ejecuta git submodule update --remote, Git irá a sus submódulos y buscará y actualizará todo por usted.

Este comando asumirá de forma predeterminada que desea actualizar la rama master del repositorio de submódulos. Sin embargo, puede establecer esto en algo diferente si lo desea. Por ejemplo, si desea que el submódulo DbConnector rastree la rama “stable” del repositorio, puede configurarlo en su archivo .gitmodules (para que todos los demás también lo rastreen), o simplemente en su archivo .git/config local. Vamos a configurarlo en el archivo .gitmodules:

Si deja de lado los -f .gitmodules, solo hará el cambio por usted, pero probablemente tenga más sentido rastrear esa información con el repositorio para que todos los demás también lo hagan.

Cuando ejecutamos git status en este punto, Git nos mostrará que tenemos “new commits” en el submódulo.

Si configura status.submodulesummary, Git también le mostrará un breve resumen de los cambios a sus submódulos:

En este punto, si ejecuta git diff podemos ver que hemos modificado nuestro archivo .gitmodules y también que hay un número de commits que hemos eliminado y estamos listos para hacer “commit” a nuestro proyecto de submódulo.

Esto es muy bueno ya que podemos ver el registro de los commits a los que estamos a punto de hacer “commit” en nuestro submódulo. Una vez hecho el “commit”, puede ver esta información también cuando ejecuta git log -p.

Git intentará por defecto actualizar todos sus submódulos cuando ejecute git submodule update --remote así que si tiene muchos de ellos, quizás quiera pasar el nombre del submódulo que desea intentar actualizar.

Es bastante probable que si está utilizando submódulos, lo esté haciendo porque realmente desea trabajar en el código dentro del submódulo al mismo tiempo que está trabajando en el código dentro del proyecto principal (o en varios submódulos). De lo contrario, probablemente usaría un sistema de administración de dependencias más simple (como Maven o Rubygems).

Así que ahora veamos un ejemplo de cómo hacer cambios en el submódulo al mismo tiempo que al proyecto principal y de hacer “commit” y publicar esos cambios conjuntamente.

Hasta ahora, cuando ejecutamos el comando git submodule update para obtener cambios de los repositorios de submódulos, Git obtendría los cambios y actualizaría los archivos en el subdirectorio, pero deja el sub-repositorio en lo que se llama un estado “detached HEAD”. Esto significa que no hay una rama de trabajo local (como “master”, por ejemplo) que rastrea los cambios. Por lo tanto, los cambios que realice no serán rastreados correctamente.

Para configurar su submódulo para que sea más fácil entrar y piratear, necesita hacer dos cosas. Necesita ingresar a cada submódulo y verificar una rama para trabajar. Entonces necesita decirle a Git qué hacer si ha hecho cambios y luego git submodule update --remote extrae un nuevo trabajo de upstream. Las opciones son que puede combinarlas en su trabajo local, o puede tratar de volver a establecer la base de su trabajo local además de los nuevos cambios.

Primero que todo, vayamos a nuestro directorio de submódulos y verifiquemos una rama.

Probemos con la opción “merge”. Para especificarlo manualmente, solo podemos agregar la opción --merge a nuestra llamada update. Aquí veremos que hubo un cambio en el servidor para este submódulo y se fusionó.

Si vamos al directorio de DbConnector, tenemos los nuevos cambios ya fusionados en nuestra rama stable local. Ahora veamos qué sucede cuando hacemos nuestro propio cambio local a la biblioteca y alguien más impulsa otro cambio en sentido ascendente al mismo tiempo.

Ahora, si actualizamos nuestro submódulo podemos ver qué sucede cuando hemos realizado un cambio local y upstream también tiene un cambio que necesitamos incorporar.

Si olvida --rebase o --merge, Git simplemente actualizará el submódulo a lo que esté en el servidor y restablecerá su proyecto a un estado detached HEAD.

Si esto sucede, no se preocupe, simplemente puede volver al directorio y verificar su rama nuevamente (que aún contendrá su trabajo) y combinar o rebasar origin/stable (o cualquier rama remota que desee) manualmente.

Si no ha hecho “commit” a los cambios en su submódulo y ejecuta una actualización de submódulo que podría causar problemas, Git buscará los cambios pero no sobrescribirá el trabajo no guardado en el directorio de su submódulo.

Si realizó cambios que entran en conflicto con algo cambiado en upstream, Git le informará cuándo ejecutar la actualización.

Puede acceder al directorio de submódulos y solucionar el conflicto tal como lo haría normalmente.

Ahora tenemos algunos cambios en nuestro directorio de submódulos. Algunos de estos fueron enviados desde el inicio por nuestras actualizaciones y otros fueron hechos localmente y todavía no están disponibles para nadie, ya que aún no los hemos promocionado.

Si hacemos “commit” en el proyecto principal y lo elevamos sin elevar los cambios del submódulo también, otras personas que intenten verificar nuestros cambios estarán en problemas ya que no tendrán forma de obtener los cambios del submódulo de los que dependen . Esos cambios solo existirán en nuestra copia local.

Para asegurarse de que esto no ocurra, puede pedirle a Git que verifique que todos sus submódulos se hayan elevado correctamente antes de empujar el proyecto principal. El comando git push toma el argumento --recurse-submodules que puede configurarse como “check” u “on-demand”. La opción “check” hará que push simplemente falle si alguno de los cambios cometidos del submódulo no ha sido elevado.

Como puede ver, también nos da algunos consejos útiles sobre lo que podríamos hacer a continuación. La opción simple es ir a cada submódulo y empujar manualmente a los controles remotos para asegurarse de que estén disponibles externamente y luego probar este empuje de nuevo.

La otra opción es usar el valor “on-demand”, que intentará hacer esto por usted.

Como puede ver allí, Git entró en el módulo DbConnector y lo empujó antes de empujar el proyecto principal. Si ese empuje del submódulo falla por algún motivo, el empuje del proyecto principal también fallará.

Si cambia una referencia de submódulo al mismo tiempo que otra persona, puede tener algunos problemas. Es decir, si los historiales de los submódulos han divergido y les han hecho “commit” a ramas divergentes en un súper proyecto, puede tomar un poco de trabajo arreglarlo.

Si uno de los commits es un antecesor directo del otro (una fusión de avance rápido), entonces Git simplemente elegirá el último para la fusión, por lo que funcionará bien.

Sin embargo, Git no intentará siquiera una fusión trivial para usted. Si los commits del submódulo divergen y necesitan fusionarse, obtendrá algo que se ve así:

Básicamente, lo que sucedió aquí es que Git ha descubierto que las dos ramas registran puntos en la historia del submódulo que son divergentes y necesitan fusionarse. Lo explica como “merge following commits not found”, lo cual es confuso, pero lo explicaremos en un momento.

Para resolver el problema, debe averiguar en qué estado debería estar el submódulo. Curiosamente, Git no le da demasiada información para ayudarle aquí, ni siquiera los SHA-1 de las commits de ambos lados de la historia. Afortunadamente, es fácil de entender. Si ejecuta git diff, puede obtener los SHA-1 de los commits registrados en ambas ramas que estaba intentando fusionar.

Entonces, en este caso, eb41d76 es el “commit' en nuestro submódulo que nosotros teníamos y c771610 es el ``commit” que tenía upstream. Si vamos a nuestro directorio de submódulos, ya debería estar en eb41d76 ya que la fusión no lo habría tocado. Si por alguna razón no es así, simplemente puede crear y verificar una rama que lo señale.

Lo que es importante es el SHA-1 del “commit” del otro lado. Esto es lo que tendrá que fusionar y resolver. Puede simplemente probar la fusión con el SHA-1 directamente, o puede crear una rama para él y luego intentar fusionar eso. Sugeriríamos esto último, aunque sea para poder hacer un mejor mensaje de “commit” de fusión.

Por lo tanto, accederemos a nuestro directorio de submódulos, crearemos una rama basada en ese segundo SHA-1 de git diff y fusionaremos manualmente.

Aquí tenemos un conflicto de fusión real, por lo que si resolvemos eso y le hacemos “commit”, podemos simplemente actualizar el proyecto principal con el resultado.

Puede ser un poco confuso, pero realmente no es muy difícil.

Curiosamente, hay otro caso que maneja Git. Si existe un “commit” de fusión en el directorio del submódulo que contiene ambos commits en su historial, Git lo sugerirá como posible solución. Se ve que en algún punto del proyecto del submódulo, alguien fusionó las ramas que contienen estos dos commits, así que tal vez querrá esa.

Esta es la razón por la cual el mensaje de error de antes era “fusionar los siguientes commits no encontrado”, porque no podía hacer esto. Es confuso porque ¿quién esperaría que intentara hacer esto?

Si encuentra un único commit de fusión aceptable, verá algo como esto:

Lo que está sugiriendo que haga es actualizar el índice como si hubiera ejecutado git add, que borra el conflicto y luego haga “commit”. Sin embargo, probablemente no debería hacer esto. También puede acceder fácilmente al directorio de submódulos, ver cuál es la diferencia, avanzar rápidamente a este “commit”, probarlo correctamente y luego hacerle “commit”.

Esto logra lo mismo, pero al menos de esta manera puede verificar que funcione y que tenga el código en el directorio de su submódulo cuando haya terminado.

Hay un comando de submódulo foreach para ejecutar algún comando arbitrario en cada submódulo. Esto puede ser realmente útil si tiene un varios submódulos en el mismo proyecto.

Por ejemplo, digamos que queremos comenzar una nueva característica o hacer una corrección de errores y tenemos trabajo sucediendo en varios submódulos. Podemos esconder fácilmente todo el trabajo en todos nuestros submódulos.

Entonces podemos crear una nueva rama y cambiar a ella en todos nuestros submódulos.

¿Entiende la idea? Una cosa realmente útil que puede hacer es producir una buena diff unificada de lo que ha cambiado en su proyecto principal y todos sus subproyectos también.

Aquí podemos ver que estamos definiendo una función en un submódulo y llamándola en el proyecto principal. Obviamente, este es un ejemplo simplificado, pero con suerte le dará una idea de cómo esto puede ser útil.

Es posible que desee configurar algunos alias para algunos de estos comandos, ya que pueden ser bastante largos y no puede establecer opciones de configuración para la mayoría de ellos para que sean predeterminados. Cubrimos la configuración de alias de Git en Alias de Git, pero aquí hay un ejemplo de lo que puede querer configurar si planea trabajar mucho con submódulos en Git.

De esta forma, simplemente puede ejecutar git update cuando desee actualizar sus submódulos, o git push para presionar con la comprobación de dependencia de submódulos.