HOWTO · Git
Extraiga el último submódulo de Git
En este artículo, presentaremos los submódulos de Git.
En esta página
Un submódulo de Git es un repositorio independiente ubicado dentro de un repositorio principal. El repositorio principal registra un commit específico del submódulo, por lo que «actualizar» puede significar restaurar ese commit registrado o avanzar el submódulo a un commit más reciente de su remoto. Desde el repositorio principal, usa git submodule update --init --recursive para inicializar los submódulos que falten y cambiar a los commits registrados por el repositorio principal. Para seguir un commit más reciente de la rama de seguimiento remoto, usa git submodule update --remote --recursive; después, revisa y confirma en el repositorio principal el cambio en el puntero del submódulo.
Cómo funciona una actualización de submódulo de Git
Un submódulo tiene su propio historial de commits y su propia configuración de remoto. El repositorio principal almacena un gitlink: una referencia a un commit de ese repositorio anidado. Por tanto, clonar o cambiar a una revisión del repositorio principal no significa que el directorio del submódulo ya esté poblado ni que siga la punta de una rama remota.
git submodule update cambia al commit registrado por el commit actual del repositorio principal. Es la opción reproducible cuando quieres usar las dependencias declaradas por el proyecto. La opción --init registra e inicializa los submódulos descritos en .gitmodules; --recursive también aplica la operación a los submódulos anidados. Estas opciones no significan «obtener el commit más reciente».
Inicializar y actualizar submódulos a los commits registrados
Ejecuta este comando desde la raíz del repositorio principal después de una clonación nueva que no haya inicializado los submódulos, o después de cambiar a un commit del repositorio principal que los incluya:
git submodule update --init --recursive
Git inicializa las rutas configuradas cuando hace falta y cambia a cada commit registrado por el repositorio principal. Si un submódulo ya está inicializado, el comando también lleva su árbol de trabajo al commit registrado. Ese cambio puede dejar el submódulo en un HEAD separado, lo cual es normal para un commit fijado por el repositorio principal. Para ver qué punteros de submódulos difieren del commit actual del repositorio principal, consulta git status en dicho repositorio.
Obtener commits remotos más recientes para los submódulos
Para actualizar los submódulos desde sus ramas de seguimiento remoto configuradas, ejecuta git submodule update --remote --recursive desde el repositorio principal. Git obtiene datos del remoto configurado y cambia al commit seleccionado por la rama configurada del submódulo. Si no se especifica una rama para un submódulo, Git usa la rama predeterminada de su remoto. Esto no garantiza obtener el commit más reciente de todas las ramas o de todos los remotos: el resultado depende de la rama configurada y del estado de seguimiento remoto que se haya obtenido.
Una actualización remota cambia el commit al que está el submódulo y hace que el repositorio principal muestre el puntero del submódulo como modificado. Revisa ese cambio antes de confirmarlo. Si solo quieres obtener datos remotos sin cambiar el commit actual, ejecuta la obtención dentro del submódulo e inspecciona sus ramas, en lugar de usar --remote para cambiar de commit.
Clonar un repositorio con sus submódulos
Para clonar un repositorio e inicializar sus submódulos de forma recursiva en un solo paso, usa git clone --recurse-submodules <repository-url>. Sustituye el marcador de posición por la URL del repositorio. Un git clone <repository-url> normal obtiene el repositorio principal, pero no inicializa los árboles de trabajo de sus submódulos; después de esa clonación, ejecuta git submodule update --init --recursive desde el nuevo directorio del repositorio principal.
La opción recursiva también inicializa los submódulos anidados dentro de otros submódulos. La operación cambia a los commits registrados por el repositorio principal clonado, por lo que este flujo es adecuado cuando quieres las versiones seleccionadas por ese proyecto.
Confirmar y enviar cambios de submódulos
Cuando hagas un cambio dentro de un submódulo, primero confírmalo y envíalo desde el repositorio de ese submódulo. Si el submódulo está en el commit fijado por el repositorio principal, puede encontrarse en un HEAD separado; por eso, antes de publicarlo, elige la rama remota que corresponda. Si el cambio debe incorporarse a una rama existente, cámbiate a ella e integra allí el cambio; de lo contrario, crea una rama. Comprueba la configuración del remoto y de la rama del submódulo, y confirma que esa es la rama que deben usar tus colaboradores. Luego confirma el cambio con git add y git commit, y envía la rama, por ejemplo, con git push <remote> <branch>. Si decides mantener HEAD separado, publica explícitamente su commit actual con git push <remote> HEAD:<branch>; sustituye los marcadores de posición por el remoto elegido y la rama de destino. Asegúrate de que el commit enviado esté disponible para los colaboradores que obtendrán el repositorio principal.
Vuelve al repositorio principal solo después de publicar el commit del submódulo. Su estado mostrará que el puntero del submódulo cambió; prepara esa ruta y confirma el cambio en el repositorio principal, por ejemplo, con git add path/to/submodule y luego git commit -m "Update submodule pointer". Envía el commit del repositorio principal por separado, como de costumbre. El commit principal registra el nuevo ID del commit del submódulo, mientras que el commit del submódulo pertenece al repositorio anidado. Enviar solo el repositorio principal no publica un commit del submódulo que aún no se haya enviado; enviar solo el submódulo tampoco cambia el commit registrado por el repositorio principal.