Todo lo que hemos visto en el módulo daba por supuesta una cosa: que la base de datos de objetos estaba sana. El reflog encontraba el hash, git branch creaba el puntero, git show leía el commit. Los objetos estaban donde tenían que estar y su contenido era el correcto.

Esta lección se ocupa de cuando no lo está.

Es el mensaje que más asusta de todo el curso, y hay que empezar por dos cosas.

La primera es que casi nunca es corrupción de verdad. La mayoría de los mensajes alarmantes tienen causas mundanas: un disco lleno, un proceso interrumpido, un antivirus que bloqueó un fichero. Antes de "reparar" nada, hay que descartar eso.

La segunda es la que hace habitable esta lección: en un sistema distribuido, cada clon es una copia de seguridad casi completa. El repositorio de Bruno tiene los mismos objetos que el tuyo. El servidor también. Ese es, casi siempre, el camino de recuperación más rápido, y muchas veces el correcto es directamente volver a clonar en lugar de intentar arreglar nada.

Vamos a ver cómo distinguir corrupción real de otra cosa, cómo leer git fsck sin asustarse, cómo reparar los casos frecuentes ordenados de menor a mayor gravedad, y —lo más importante— cuándo dejar de intentarlo.

1. Cuándo sospechar corrupción y cuándo es otra cosa
2. Las causas reales de la corrupción
3. git fsck como herramienta de diagnóstico
4. Reparaciones, de menor a mayor gravedad
5. La red de seguridad del modelo distribuido
6. Reconstruir un repositorio conservando tu trabajo
7. Prevención: mantenimiento y copias de seguridad de verdad
8. Cuándo dejar de reparar y volver a clonar

Antes de nada, la tabla de descarte. Muchos errores que parecen corrupción no lo son.

Antes de tocar nada de .git:

Si ves Use% 100%, ese es el problema. Libera espacio antes de seguir; cualquier reparación va a escribir objetos y fallará igual.

Si en lugar de ext4/apfs/ntfs local ves nfs, cifs, fuse.sshfs o una ruta dentro de Dropbox, OneDrive, iCloud o Google Drive, ya tienes la explicación, y es el apartado 2.

Git es notablemente robusto. Los objetos son inmutables, se escriben una vez, y cada uno lleva su propia suma de verificación: el nombre del objeto es el hash de su contenido, así que cualquier alteración se detecta al leerlo (lección 01-04). La corrupción, cuando ocurre, casi siempre viene de fuera.

No pongas un repositorio Git dentro de una carpeta sincronizada por la nube.

Es la causa clásica, y el razonamiento es sencillo: Git escribe muchos ficheros pequeños en un orden concreto (objeto, luego índice, luego referencia). Un sincronizador los sube según su propio criterio y velocidad. Si trabajas desde dos máquinas, el sincronizador puede combinar un .git/index de una con las referencias de la otra, o crear ficheros del tipo main (conflicted copy 2026-07-28).lock.

El resultado es un repositorio en un estado que Git nunca podría haber producido.

Y lo irónico: no hace ninguna falta. Git ya es un sistema de sincronización distribuido. Para tener el proyecto en dos máquinas, la respuesta es un remoto, no Dropbox.

Si de verdad necesitas que un repositorio viva ahí, la única forma segura es que sea un repositorio desnudo (--bare) usado como remoto, al que nunca se escribe desde dos sitios a la vez. Aun así, git bundle (apartado 7) es mejor idea.

Si Carla trabaja en Windows 11 y sufre errores intermitentes:

Y en Git for Windows, un ajuste que reduce problemas con antivirus y con sistemas de ficheros lentos:

git fsck (file system check) recorre la base de objetos, verifica que el contenido de cada objeto coincide con su hash, y comprueba que todas las referencias entre objetos se resuelven.

Opciones útiles:

Esta es la tabla que evita el pánico innecesario.

La regla de oro para leer fsck:

Si eso no devuelve nada, tu repositorio está sano. Punto. Todo lo que hayas visto era ruido.

Tres líneas alarmantes en apariencia, cero problemas. Son los restos del reset --hard de la semana pasada y de un git add que no llegó a confirmarse. Un repositorio activo siempre tiene esto.

Aquí sí hay trabajo. Una referencia rota y un objeto ilegible, con el árbol que lo necesita identificado. Es el apartado 4.

Ese mensaje, para un hash que sabes que existía, es la confirmación de que el objeto ha desaparecido.

o

No has perdido nada. Y la razón es conceptualmente importante:

El índice es un caché derivado. No contiene información única: es una foto de qué debería haber en el próximo commit, reconstruible enteramente a partir de HEAD y del directorio de trabajo.

Por eso la reparación es de las más agradecidas de Git:

Lo único que se pierde es qué estaba preparado con git add: tras la reconstrucción, todas tus modificaciones aparecen como no preparadas. Los cambios en sí están intactos, porque viven en los ficheros del disco, no en el índice.

Un matiz importante: usa git reset (--mixed), nunca git reset --hard. El primero reconstruye el índice y deja el directorio de trabajo en paz; el segundo se llevaría por delante todas tus modificaciones (lección 09-02).

Si además tenías un conflicto de fusión a medias, la información de las etapas del índice (:1:, :2:, :3: de la lección 03-05) sí se pierde, y hay que rehacer la fusión:

Ya visto en la lección 09-01, aquí en su versión completa. Los cerrojos son ficheros .lock que Git crea antes de escribir y borra al terminar:

El procedimiento:

Un caso especial que merece cuidado: .git/config.lock. Si Git murió escribiendo la configuración, el fichero .git/config puede haber quedado truncado. Compruébalo antes de borrar el cerrojo:

Si está roto, la configuración local es lo más fácil de rehacer a mano de todo el repositorio.

Qué es. El fichero refs/heads/GT-241 contiene un hash que no corresponde a ningún objeto existente. Recuerda que una rama son 41 bytes de texto (lección 03-01):

Confirmado: la referencia apunta al vacío.

Reparación A: el reflog de la rama. Es la mejor opción, porque conserva historia:

Prueba las entradas de arriba abajo hasta encontrar una válida:

Has perdido el último commit, pero recuperas la rama. Mucho mejor que nada.

Reparación B: packed-refs. Las referencias también viven consolidadas en un fichero (lección 08-06):

A veces la versión empaquetada es válida aunque la suelta esté rota. Borrando la suelta, Git usa la empaquetada:

Reparación C: el remoto.

Reparación D: si la rama no importa, borrarla.

Y la limpieza masiva, cuando hay muchas referencias rotas:

Este es el caso serio.

Primer paso, el diagnóstico exacto:

Cero bytes: escritura interrumpida. Es el patrón típico de disco lleno o apagón.

La reparación que casi siempre funciona: traerlo de otro clon.

Esta es la idea central de la lección y el apartado 5 la desarrolla. Los objetos de Git son idénticos en todas partes: el mismo contenido produce el mismo hash y el mismo fichero comprimido. Si Bruno tiene ese commit, su objeto sirve exactamente igual.

Si el otro clon lo tiene empaquetado en lugar de suelto, hay que extraerlo:

Si el hash resultante coincide con el que faltaba, la reparación es exacta. Y no puede no coincidir: el hash se calcula del contenido, así que si sale otro, el contenido no era el mismo (lección 01-04).

Para un objeto de tipo tree o commit, el mismo procedimiento con -t tree / -t commit y el contenido exacto que da cat-file -p en el clon sano.

Si el objeto era un packfile dañado:

Un packfile roto es peor, porque contiene miles de objetos y las cadenas de delta dependen unas de otras (lección 08-06). Se puede intentar extraer lo salvable:

Pero seamos claros: con un packfile dañado, la respuesta correcta casi siempre es reclonar (apartado 8). Extraer objetos de un pack roto es un ejercicio de arqueología que rara vez compensa cuando hay un clon sano a un git clone de distancia.

HEAD es un fichero de texto de una línea (lección 03-01):

Lo que debería contener:

Lo que puede haber pasado:

Si no queda ninguna rama válida, el reflog de HEAD sigue siendo texto plano y legible aunque Git no funcione:

Es el fichero más fácil de reparar, porque su contenido es trivial de rehacer:

Si está truncado, edítalo (aquí sí, con un editor de texto: config es texto plano por diseño y Git no lo verifica con hashes) o reconstruye lo esencial:

Aquí está la idea que convierte esta lección en algo manejable, y que cierra el círculo del módulo 1.

En un sistema centralizado, el servidor es un punto único de fallo: si se corrompe, se ha corrompido el proyecto. En Git, cada clon contiene todo el historial. Ana, Bruno, Carla, Diego y el servidor tienen cinco copias completas de la base de objetos.

Consecuencia práctica: cuando tu repositorio se corrompe, la pregunta correcta no es "¿cómo lo reparo?" sino "¿qué tengo yo que no tenga nadie más?".

GT-241 no tiene upstream: existe solo en esta máquina. Es lo único que hay que salvar.

Con esas cuatro respuestas ya sabes exactamente cuánto vale la reparación. Si la respuesta es "nada, todo está publicado", reclonar tarda dos minutos y es la solución perfecta.

Y si el problema es del servidor, la dirección se invierte: cualquier clon del equipo puede reconstruirlo.

--mirror copia todas las referencias tal cual: ramas, etiquetas, notas. Es la forma correcta de duplicar un repositorio desnudo.

El procedimiento completo, cuando has decidido reclonar pero tienes cosas locales que salvar.

Aunque vayas a reclonar. Cuesta diez segundos y es lo único que impide que un error durante el rescate sea definitivo.

git bundle empaqueta commits en un solo fichero que funciona como un remoto. Es la herramienta correcta para esto, y funciona incluso si el repositorio está parcialmente dañado (mientras los objetos implicados estén sanos).

Si además tienes cambios sin confirmar, sácalos aparte:

Si git bundle falla porque el repositorio está demasiado dañado, la vía bruta también sirve:

Se pierde el historial de las ramas locales, pero se conserva el contenido, que suele ser lo que importaba.

Las ramas locales han vuelto, con todos sus commits.

Si no hay errores y todo tu trabajo está ahí:

No borres la copia hasta haber verificado. Es la única regla que importa de este apartado.

Retomando la lección 08-06:

Además de mejorar el rendimiento, mantiene la base de objetos ordenada y reduce el número de ficheros sueltos expuestos a escrituras interrumpidas.

Y una comprobación periódica, que en un repositorio normal tarda segundos:

Y una configuración que hace que Git verifique los objetos al recibirlos, detectando la corrupción en el momento en lugar de meses después:

Cuesta un poco de tiempo en cada fetch y a cambio impide que un objeto malformado entre en tu repositorio. En el servidor, receive.fsckObjects es directamente obligatorio.

Un bundle es un único fichero con todo lo que le pidas, que funciona como un remoto. Es portátil, verificable y no depende de ningún servicio.

Y copias incrementales, si el repositorio es grande:

Un guion de copia semanal:

Por qué un bundle es mejor que copiar .git con cp:

1. Nunca un repositorio en una carpeta sincronizada por la nube. La causa número uno. Usa un remoto.

2. Nunca .git en un volumen de red si puedes evitarlo. Clona en local y publica.

3. Excluye tus carpetas de proyectos del antivirus en Windows.

4. Vigila el espacio en disco. Un df -h de vez en cuando.

5. git maintenance start en los repositorios de trabajo.

6. transfer.fsckObjects true para detectar la corrupción cuando entra.

7. Publica tus ramas. Una rama publicada está en dos máquinas. Es la mejor copia de seguridad y la más barata.

8. git bundle semanal de lo que solo tienes tú.

9. No mates procesos de Git con kill -9, especialmente durante gc o repack.

10. No edites ficheros de .git a mano (salvo config, que es texto por diseño). Usa git update-ref, git symbolic-ref, git config.

La decisión más importante de la lección, y la que más tiempo ahorra.

Reclonar es la respuesta correcta cuando:

• El repositorio está completamente publicado (nada local sin enviar). Entonces reclonar no tiene ningún coste.
• Hay un packfile dañado. Extraer objetos de un pack roto rara vez compensa.
• git fsck devuelve más de un puñado de errores.
• La corrupción reaparece tras repararla: hay una causa de fondo (disco, nube, antivirus) que no has resuelto.
• Llevas más de treinta minutos intentando repararlo. El coste de un git clone es de minutos; el de una tarde de arqueología, no.

Merece la pena intentar la reparación cuando:

• El problema es el índice, un cerrojo, HEAD o config. Son minutos y no se pierde nada.
• Es una referencia rota y el reflog o packed-refs la resuelven.
• Falta un objeto y sabes de dónde traerlo.
• Tienes trabajo local importante sin publicar y necesitas extraerlo antes de reclonar (apartado 6).

En forma de árbol:

Y la frase que resume la lección:

Un repositorio Git dañado no es un problema de datos: es un problema de logística. Los datos casi siempre están en otro sitio. Tu trabajo consiste en identificar qué es exclusivamente tuyo, salvarlo, y traer el resto de donde esté sano.

Error 1: asustarse con los dangling de git fsck. Son completamente normales en cualquier repositorio activo. Filtra con grep -v "^dangling" y mira si queda algo.

Error 2: dar por corrupto lo que es un disco lleno. df -h es el primer comando. Reparar con el disco al 100 % no puede funcionar.

Error 3: tener el repositorio en Dropbox, OneDrive o iCloud. Es la causa número uno de corrupción real, y no hace ninguna falta: Git ya sincroniza.

Error 4: git reset --hard para reparar un índice corrupto. rm .git/index && git reset reconstruye sin tocar tus ficheros; con --hard los perderías todos.

Error 5: editar ficheros de .git con un editor de texto. Salvo config, usa los comandos: git update-ref, git symbolic-ref, git config.

Error 6: reparar sin haber hecho una copia. cp -a cuesta diez segundos y evita que un error durante el rescate sea definitivo.

Error 7: pasar horas reparando un repositorio que está íntegramente publicado. Comprueba primero qué tienes que no tenga nadie más. Si la respuesta es "nada", reclona.

Error 8: usar cp -a .git como copia de seguridad "oficial". Vale para una emergencia, pero puede copiar un estado a medias. git bundle es coherente y verificable.

Error 9: borrar el repositorio roto antes de verificar el nuevo. Verifica con git fsck y comprueba que todo tu trabajo está ahí; luego borra.

Consejo 1: aprende el filtro de fsck. git fsck --full --no-progress 2>&1 | grep -vE "^(dangling|notice)". Si no devuelve nada, estás sano.

Consejo 2: git bundle create ... --all semanal. Un fichero, verificable, restaurable con git clone.

Consejo 3: transfer.fsckObjects true en la configuración global. Detecta la corrupción cuando entra, no meses después.

Consejo 4: publica tus ramas. Es la copia de seguridad más barata y la que más veces salva.

Consejo 5: el índice es un caché. Perderlo no tiene importancia; recordarlo evita mucho pánico innecesario.

Consejo 6: pon un límite de tiempo. Treinta minutos de reparación y, si sigue roto, reclona. El clon tarda dos.

1. Crea un repositorio con diez commits, una rama con tres commits propios y un git add sin confirmar.
2. Provoca objetos colgantes: un reset --hard HEAD~3, un commit --amend y un branch -D.
3. Ejecuta git fsck --full y cuenta cuántas líneas devuelve.
4. Aplica el filtro del consejo 1 y comprueba que no queda nada. Explica por qué el repositorio está sano pese a las líneas anteriores.
5. Identifica, entre los colgantes, cuál corresponde al git add sin confirmar y recupéralo con git cat-file -p.

Sobre un repositorio de pruebas (nunca sobre uno real):

1. Corrompe el índice: printf 'basura' > .git/index. Ejecuta git status y anota el error. Repáralo y explica por qué no se pierde nada.
2. Rompe una referencia: echo "0000000000000000000000000000000000000000" > .git/refs/heads/GT-241. Ejecuta git fsck y repárala con el reflog.
3. Rompe HEAD: echo "ref: refs/heads/inexistente" > .git/HEAD. Diagnostica y repara con git symbolic-ref.
4. Vacía un objeto suelto: localiza uno con find .git/objects -type f y trúncalo con : > <fichero>. Ejecuta git fsck --full y observa el error.
5. Repara el punto 4 desde un clon sano que habrás hecho antes de romper nada.
6. Después de cada reparación, ejecuta git fsck --full filtrado y confirma que está limpio.

1. Monta un remoto local con git init --bare y clónalo.
2. En el clon, publica dos commits en main y crea dos ramas locales sin publicar con tres commits cada una. Añade un stash y algún cambio sin confirmar.
3. Haz el inventario del apartado 5: qué ramas no tienen upstream, qué commits no están en el remoto.
4. Crea un bundle con todo lo local y verifícalo.
5. Borra el clon entero (simulando corrupción irreparable) y vuelve a clonar.
6. Reincorpora las dos ramas desde el bundle y comprueba que los seis commits están.
7. Explica qué se ha perdido y qué no, y cómo lo habrías evitado publicando las ramas.

Solución 1:

Nueve líneas de aspecto preocupante.

Cero errores. El repositorio está perfectamente sano.

La razón: dangling significa "este objeto existe y es legible, pero ninguna referencia lo alcanza". Es exactamente el resultado esperado de un reset, un --amend y un branch -D: los commits siguen ahí (por eso son recuperables, lección 09-04) pero ya no cuelgan de ninguna rama. Es lo contrario de un problema: es la prueba de que la red de seguridad funciona.

Los errores de verdad empiezan por error:, missing o broken link, y aquí no hay ninguno.

Solución 2:

Nada perdido. La modificación seguía en el fichero del disco; el índice solo era la foto de qué iba a entrar en el próximo commit, y se reconstruye desde HEAD más el directorio de trabajo. Es un caché.

Reparada, y con su commit. El reflog conservaba el hash correcto porque el fichero de reflog es independiente del fichero de referencia.

Git no falla, pero cree estar en una rama que no existe: git log no muestra nada y un commit crearía una rama nueva.

Git se niega a operar: no puede leer un objeto que necesita.

El hash coincide, así que la reparación es demostrablemente exacta. No puede ser de otra manera: el nombre del objeto es el hash de su contenido (lección 01-04), de modo que si el hash sale igual, el contenido es idéntico byte a byte. Esta propiedad es la que hace que reparar un repositorio Git desde otro clon sea seguro y verificable.

Solución 3:

Seis commits, dos ramas, un stash y dos cambios existen únicamente en esta máquina. Ese es exactamente el valor de la reparación.

Solo lo publicado.

Los seis commits y las dos ramas, con sus hashes originales.

Lo que se ha perdido:

• La pila de stashes como tal. El contenido se ha reaplicado desde el parche, pero la entrada stash@{0} no existe. (Un bundle con --all habría incluido refs/stash.)
• Todo el reflog, que es local y no viaja (lección 09-04). El clon nuevo tiene tres entradas.
• Las ramas de seguimiento antiguas y la configuración local del repositorio.

Lo que no se ha perdido: ni un solo commit, ni un solo cambio.

Cómo se habría evitado: publicando las ramas.

Con las dos ramas publicadas, el inventario del paso 3 habría salido vacío, y toda esta lección se habría reducido a rm -rf trabajo && git clone. Dos segundos de push frente a veinte minutos de rescate.

La corrupción de un repositorio Git asusta mucho más de lo que cuesta.

• La mayoría de los mensajes alarmantes no son corrupción: un cerrojo huérfano, un disco lleno, un problema de permisos o de propiedad. Descártalo primero con df -h y ls -ld .git.
• Las causas reales vienen casi siempre de fuera de Git: un repositorio en una carpeta sincronizada con la nube (la número uno), un disco lleno, un apagón, un volumen de red, un antivirus. Los objetos de Git son inmutables y llevan su propia verificación; Git rara vez se rompe solo.
• git fsck se lee filtrando el ruido. Los objetos dangling son completamente normales —son los restos de cada reset, rebase y --amend— y su presencia es la prueba de que la red de seguridad de la lección 09-04 funciona. Lo grave empieza por error:, missing o broken link.
• Las reparaciones, de menor a mayor: el índice es un caché derivado y se reconstruye con rm .git/index && git reset sin perder nada; los cerrojos se borran tras comprobar procesos; una referencia rota se repara con el reflog, packed-refs o el remoto; HEAD con git symbolic-ref; un objeto ilegible trayéndolo de otro clon, con la garantía de que si el hash coincide, la reparación es exacta.
• El modelo distribuido es la red de seguridad. Cada clon del equipo es una copia casi completa. La pregunta correcta ante un repositorio dañado no es "¿cómo lo reparo?" sino "¿qué tengo yo que no tenga nadie más?", y se responde con git for-each-ref y git log --branches --not --remotes.
• El rescate se hace con git bundle: empaquetar lo local en un fichero, reclonar, y reincorporarlo con git fetch <bundle>. Y siempre con un cp -a previo y una verificación posterior antes de borrar nada.
• Prevención: nada de repositorios en la nube ni en volúmenes de red, git maintenance start, transfer.fsckObjects true, git bundle periódico y —lo que más rinde— publicar las ramas.
• Y el criterio: si todo está publicado, reclona. Tarda dos minutos y es la respuesta correcta. Reserva la reparación para el índice, los cerrojos, HEAD y las referencias, o para extraer trabajo local antes de reclonar.

Con esto, el módulo ha cubierto los cuatro problemas que anunciaba el cierre del módulo 8: el reset --hard desafortunado, el enredo con el remoto, la rama borrada y el repositorio que se niega a funcionar.

Queda lo transversal. Porque muchas veces el problema no es que Git esté roto ni que hayas perdido algo, sino que Git está haciendo algo que no entiendes: un fichero que se ignora cuando no debería, una configuración que viene de un sitio que no sabías que existía, un push que falla por razones opacas, un cambio de comportamiento que nadie recuerda haber introducido. Para eso hay una caja de herramientas propia —trazas, fontanería, check-ignore, check-attr, ls-files— y, sobre todo, un método.

Continúa en la lección 09-06: Técnicas Avanzadas de Depuración.