¿Git worktree falla tras mover una carpeta? Audita ambos enlaces antes de reparar o borrar

1. Conserva las pruebas

Detén los trabajos de limpieza, la recolección de basura, las acciones del IDE para eliminar espacios de trabajo y los scripts que llamen a`git worktree prune`. No vuelvas a mover ninguno de los directorios durante la auditoría.

Copia a un lugar seguro cada directorio afectado que contenga cambios sin confirmar o archivos sin seguimiento. Una relación de registro rota no convierte la carpeta en material desechable.

Desde un worktree donde todavía funcionen los comandos de Git, guarda:

```sh git --version git worktree list --porcelain git worktree prune --dry-run --verbose ```

La simulación sirve solo para diagnosticar. Si propone quitar un worktree cuyos archivos existen en una ruta nueva, detente: demuestra un registro obsoleto, no autoriza a ejecutar prune.

Para cada directorio, registra además la ruta absoluta, si existe y si funciona`git status --porcelain=v1`. Guarda su salida si funciona; si falla, conserva el primer error exactamente.

No pegues credenciales, URL remotas con tokens ni contenido de archivos privados en un informe de soporte.

2. Construye un registro de enlaces en ambas direcciones

Un worktree enlazado normalmente contiene un pequeño archivo`.git` que apunta a su directorio privado bajo`.git/worktrees/` del principal. Dentro de ese directorio, el registro`gitdir` apunta de vuelta al directorio de trabajo enlazado. La relación tiene dos direcciones.

Usa una fila por worktree:

| Campo | Qué registrar | | --- | --- | | Nombre del worktree | Nombre neutro, sin proyectos secretos | | Directorio actual | Ruta que existe ahora | | Directorio listado | Ruta de`git worktree list --porcelain` | | Destino de`.git` enlazado | Destino`gitdir:`, registrado sin editar | | Destino`gitdir` del principal | Ruta recíproca en`.git/worktrees/<id>/gitdir` | | Rama o detached HEAD | Lista porcelain o HEAD conservado | | Cambios y archivos sin seguimiento | Resumen exacto o estado no disponible | | Simulación de prune | Ninguna acción o propuesta literal de retirada | | Ruta de otra aplicación | Ruta guardada fuera de Git | | Decisión | Principal movido, enlazado movido, ambos, huérfano o desconocido |

No identifiques el registro correcto solo por el nombre del directorio. Dos worktrees pueden tener nombres parecidos y el nombre del directorio administrativo no sustituye a la ruta actual.

3. Clasifica el traslado antes de ejecutar repair

Elige una de estas ramas a partir del registro.

Solo se movió el worktree principal

El archivo`.git` del enlazado sigue apuntando a la ubicación antigua del principal; sus comandos pueden fallar. El principal nuevo conserva los registros privados de los worktrees.

Ejecuta desde el nuevo worktree principal:

```sh git worktree repair ```

La documentación de Git indica que esto restablece la conexión del enlazado al principal trasladado.

Solo se movió un worktree enlazado

Los comandos dentro del enlazado pueden seguir funcionando porque su puntero alcanza el principal, pero el`gitdir` del principal conserva la ruta antigua. La lista puede marcar esa ruta como`prunable`.

Ejecuta dentro del worktree enlazado que moviste:

```sh git worktree repair ```

Después verifica desde el principal que la lista porcelain muestra la ruta nueva.

Se movieron varios worktrees enlazados

Desde un worktree que alcance el repositorio principal, proporciona todas las rutas nuevas:

```sh git worktree repair /new/path/alpha /new/path/beta ```

Usa rutas absolutas durante el diagnóstico, salvo que hayas adoptado deliberadamente una política de enlaces relativos y la hayas probado.

Se movieron el principal y los enlazados

Ejecuta desde el principal nuevo e indica la nueva ruta de cada worktree enlazado:

```sh git worktree repair /new/path/alpha /new/path/beta ```

Esta rama repara explícitamente las dos direcciones cuando ambos extremos se trasladaron manualmente.

El directorio existe, pero no está registrado

No interpretes “no registrado” como “seguro para borrar”. Puede contener trabajo pendiente aunque falte el registro administrativo. Consérvalo, inspecciona sus archivos y exclúyelo de la eliminación automática.`repair` no inventa una identidad administrativa correcta cuando se desconoce la relación.

Si verificas que es un residuo prescindible, eliminarlo es otra decisión posterior a la inspección, no una consecuencia automática de un fallo de Git.

4. Verifica la relación reparada

Después de repair, repite las mismas comprobaciones de lectura desde el principal y cada enlazado:

```sh git worktree list --porcelain git worktree prune --dry-run --verbose git status --porcelain=v1 git rev-parse --path-format=absolute --git-dir git rev-parse --path-format=absolute --git-common-dir ```

Acepta la reparación solo si se cumple todo lo siguiente:

1. Cada worktree previsto aparece una sola vez en su ruta actual. 2. Ningún worktree existente queda marcado`prunable`. 3. Cada enlazado resuelve el directorio común esperado. 4. Se conserva la identidad de rama o detached HEAD. 5. Siguen presentes los archivos modificados y sin seguimiento registrados antes. 6. La simulación de prune no propone quitar un worktree existente. 7. El IDE o espacio de trabajo abre la ruta correcta, o se registra como otro problema pendiente.

Si falla cualquier punto, detente. Guarda las pruebas y no escales a opciones de fuerza.

5. Separa repair, prune, remove y lock

`git worktree repair` actualiza enlaces administrativos obsoletos o dañados. Es el comando normal cuando se ha movido el principal o un enlazado.

`git worktree prune` retira información administrativa de worktrees cuyos directorios ya no existen. No es la primera solución para una carpeta simplemente trasladada. Inspecciona siempre la simulación.

`git worktree remove` retira un worktree registrado que ya no necesitas. Git normalmente rechaza un worktree con cambios o archivos sin seguimiento;`--force` debilita esa protección y no es una estrategia de reparación.

`git worktree lock --reason "..."` protege frente al prune automático un worktree en una unidad portátil o recurso que no siempre está montado. No repara rutas incorrectas. Un worktree bloqueado requiere fuerza adicional para moverlo o eliminarlo.

Estos comandos tienen fines distintos. Git no admite`worktree move` para el principal ni para un enlazado con submódulos; su manual tampoco recomienda varios checkouts de un superproyecto. Estos ejemplos no resuelven esas limitaciones. Conserva las pruebas e investiga esa estructura por separado.

6. Trata los registros de otra aplicación como una capa aparte

Un producto de espacios de trabajo puede guardar una ruta absoluta en su propia base de datos. Tras un`git worktree move` admitido, Git puede listar correctamente la nueva ruta mientras el producto sigue abriendo la antigua.

Prueba primero el estado de Git con las comprobaciones anteriores. Después consulta el procedimiento documentado del producto para cambiar la ruta, importar o recrear. No vuelvas a alterar metadatos de Git para satisfacer un registro de aplicación desactualizado.

Registra el resultado de esa aplicación por separado:

- Git correcto, ruta del producto actualizada. - Git correcto, producto sin operación para cambiar la ruta. - Git correcto, recreación del registro necesaria y posible pérdida de estado de la aplicación. - Git sigue incorrecto: vuelve al registro de enlaces de Git.

Esta separación evita diagnosticar una limitación del producto como un fallo de repair.

7. Qué mostró la prueba en repositorios desechables

En un repositorio temporal con Git 2.51.1 se crearon un worktree principal y otro enlazado, y se colocó un archivo sin seguimiento en el enlazado.

Tras mover manualmente ambos directorios, la lista del principal marcó la antigua ruta enlazada como`prunable`; la simulación propuso retirar el registro administrativo y`git status` falló en el enlazado nuevo. Ejecutar`git worktree repair <new-linked-path>` desde el principal nuevo restauró las conexiones; el archivo sin seguimiento permaneció.

Mover solo el enlazado permitió consultar su estado, pero dejó obsoleta la ruta del principal. repair dentro del enlazado nuevo actualizó la lista. Mover solo el principal rompió el puntero enlazado, que se restauró con repair desde el principal nuevo.

Los tres casos desechables se ejecutaron en Linux con Git 2.51.1. Cada repair conservó los bytes de archivos modificados y sin seguimiento, HEAD y la identidad de la rama. Se revisó la documentación actual de 2.56.0, pero no se probó ese binario. No se establece el comportamiento de todas las versiones, sistemas de red, submódulos, IDE ni bases de datos de espacios de trabajo.

Preguntas frecuentes

¿Debo editar a mano el archivo.git del enlazado?

Consérvalo como prueba, pero prefiere`git worktree repair`. Una edición de un solo extremo puede dejar obsoleto el registro recíproco del principal.

¿Por qué funciona git status en la carpeta nueva y la lista sigue mostrando la antigua?

El puntero`.git` del enlazado puede alcanzar el principal mientras su registro`gitdir` recíproco conserva la ubicación antigua. Es una reparación de una sola dirección.

¿Es seguro ejecutar prune sobre una entrada prunable?

No hasta verificar que el worktree correspondiente realmente desapareció. Un directorio trasladado que sigue existiendo puede hacer que su ruta antigua parezca prescindible.

¿Puede repair recuperar un directorio no registrado?

Solo si queda suficiente identidad administrativa para reconectar la relación. Una carpeta que parece un worktree no demuestra un registro válido. Consérvala e inspecciónala antes de borrar.

¿repair actualiza también el IDE o gestor de espacios de trabajo?

No necesariamente. Git repara sus propios metadatos. Otras herramientas pueden guardar rutas absolutas separadas y necesitar su procedimiento admitido de actualización o recreación.