Tecnología · GUÍA PRÁCTICA
¿Git no encuentra la URL del submódulo? Comprueba gitlink y .gitmodules antes de borrar
Compara el commit que falló, el índice actual, el mapeo versionado y la copia local antes de reparar, sincronizar, ejecutar deinit o eliminar del repositorio.
“No url found for submodule path” exige comprobar la relación entre ruta y URL antes de borrar metadatos de Git. El gitlink que registra el commit hijo y su sección en .gitmodules son estados separados. El índice actual, el archivo de trabajo y el commit que falló pueden no coincidir.
Conserva el error original, el commit del superproyecto que falló, la ruta y el trabajo local. Comprueba el gitlink y el mapeo guardados, revisa la configuración local y elige el cambio que realmente pretende el repositorio. Una prueba aislada con Git 2.51.1 muestra por qué un archivo correcto en disco no demuestra que se haya reparado el commit.
Comprueba por separado el commit y el índice
Guarda el error completo y verifica el commit exacto del superproyecto que utilizó la copia o el trabajo de CI que falló. Trabaja desde la raíz del superproyecto y conserva cambios sin commit antes de escribir. Ejecuta git ls-files --stage -- path/to/item para el índice actual: el modo 160000 identifica un gitlink y su objeto. Un directorio .git anidado no basta para inferirlo.
Después ejecuta git ls-tree --full-tree COMMIT -- path/to/item, sustituyendo COMMIT por el identificador verificado del commit que falló. Consulta ese árbol, sin asumir que el índice siga igual. Si allí no existe gitlink, investiga otra copia, un superproyecto anidado, cambios preparados o la ruta citada en el error antes de reparar el mapeo.
Lee el mapeo de ese mismo commit
Usa git show COMMIT:.gitmodules para leer el archivo versionado del commit que falló. Su ausencia es evidencia, no permiso para sustituirlo silenciosamente por el de otra rama. Busca una sección cuyo path coincida exactamente con el gitlink, incluidas mayúsculas. Git exige ruta única relativa a la raíz, sin barra final, y URL; el nombre de sección no tiene que ser la ruta.
Para el archivo de trabajo actual puedes usar la forma compatible git config -f .gitmodules --get-regexp '^submodule\..*\.(path|url)$'. Mantén las comillas para que el shell no interprete | como una tubería. Compara el resultado con el archivo del commit: restaurar solo un archivo sin commit en disco no cambia lo que recibe una copia limpia del commit defectuoso.
Separa la configuración local y sincroniza la URL prevista
Inspecciona las opciones locales inicializadas con git config --local --get-regexp '^submodule\..*\.(url|active)$'. Las claves emplean nombres de submódulo: relaciónalos con el path de .gitmodules. La inicialización puede rellenar la configuración desde la plantilla versionada y las modificaciones locales posteriores pueden diferir. Un submódulo desinicializado puede conservar su definición registrada sin archivos extraídos.
Si el repositorio cambió intencionadamente una URL existente, verifica el remoto aprobado, repara o actualiza .gitmodules y ejecuta git submodule sync --recursive -- path/to/item para el submódulo inicializado previsto. Revisa la URL efectiva antes de update. Sync afecta a la URL registrada; no repara mapeos ausentes, cambia el commit hijo ni autoriza acceso a un remoto privado.
Elige conservar, retirar localmente o eliminar del repositorio
Para conservar el submódulo, restaura ruta exacta y URL aprobada, prepara el mapeo, revisa el diff y crea el commit reparado previsto. Después inicializa o actualiza y prueba una copia limpia de ese commit. Si solo cambia la URL, conserva el gitlink salvo que también pretendas actualizar el commit hijo, y sincroniza las copias inicializadas afectadas.
Para retirar solo la copia local, conserva el trabajo y usa git submodule deinit -- path/to/item sin añadir --force para descartar cambios. Para eliminarlo del control de versiones, usa git rm -- path/to/item y revisa tanto el gitlink eliminado como el cambio de sección en .gitmodules antes del commit. Son resultados distintos. git rm --cached solo actúa sobre el índice y no hace la misma limpieza automática del mapeo que git rm normal.
Verifica con un clon limpio antes de culpar a la caché
En repositorios aislados con Git 2.51.1 guardamos un gitlink sin su mapeo. Un clon local nuevo reprodujo el error fatal exacto. Tanto índice como árbol guardado mostraron 160000. Añadir .gitmodules solo al disco permitió consultar el archivo de trabajo, pero git show sobre el commit defectuoso siguió fallando. Después de guardar el mapeo restaurado en un commit, un clon limpio se inicializó correctamente; deinit retiró luego el estado local mientras gitlink y mapeo guardados permanecieron intactos.
Las pruebas usaron repositorios hijos locales y permitieron el transporte file únicamente en sus comandos individuales. No reprodujeron tu CI, red ni autorización privada; esa excepción de transporte no es una reparación de producción. Sospecha una copia desechable obsoleta solo cuando los metadatos guardados sean correctos. Conserva registros y trabajo, recrea únicamente la copia desechable cuando corresponda y registra commits defectuoso y reparado y el resultado del clon limpio. No empieces borrando .git/modules, datos .git anidados ni el árbol de trabajo de un desarrollador.
