Tot el que hem vist al mòdul donava per suposada una cosa: que la base de dades d'objectes estava sana. El reflog trobava el hash, git branch creava el punter, git show llegia el commit. Els objectes eren on havien de ser i el seu contingut era el correcte.

Aquesta lliçó s'ocupa de quan no ho està.

És el missatge que més espanta de tot el curs, i cal començar per dues coses.

La primera és que gairebé mai no és corrupció de debò. La majoria dels missatges alarmants tenen causes mundanes: un disc ple, un procés interromput, un antivirus que va bloquejar un fitxer. Abans de «reparar» res, cal descartar això.

La segona és la que fa habitable aquesta lliçó: en un sistema distribuït, cada clon és una còpia de seguretat gairebé completa. El repositori del Bruno té els mateixos objectes que el teu. El servidor també. Aquest és, gairebé sempre, el camí de recuperació més ràpid, i moltes vegades el correcte és directament tornar a clonar en lloc d'intentar arreglar res.

Veurem com distingir la corrupció real d'una altra cosa, com llegir git fsck sense espantar-se, com reparar els casos freqüents ordenats de menor a major gravetat, i —el més important— quan deixar d'intentar-ho.

1. Quan sospitar corrupció i quan és una altra cosa
2. Les causes reals de la corrupció
3. git fsck com a eina de diagnòstic
4. Reparacions, de menor a major gravetat
5. La xarxa de seguretat del model distribuït
6. Reconstruir un repositori conservant la teva feina
7. Prevenció: manteniment i còpies de seguretat de debò
8. Quan deixar de reparar i tornar a clonar

Abans de res, la taula de descart. Molts errors que semblen corrupció no ho són.

Abans de tocar res de .git:

Si veus Use% 100%, aquest és el problema. Allibera espai abans de continuar; qualsevol reparació escriurà objectes i fallarà igualment.

Si en lloc d'ext4/apfs/ntfs local hi veus nfs, cifs, fuse.sshfs o una ruta dins de Dropbox, OneDrive, iCloud o Google Drive, ja tens l'explicació, i és l'apartat 2.

Git és notablement robust. Els objectes són immutables, s'escriuen un cop, i cadascun porta la seva pròpia suma de verificació: el nom de l'objecte és el hash del seu contingut, així que qualsevol alteració es detecta en llegir-lo (lliçó 01-04). La corrupció, quan passa, gairebé sempre ve de fora.

No posis un repositori Git dins d'una carpeta sincronitzada pel núvol.

És la causa clàssica, i el raonament és senzill: Git escriu molts fitxers petits en un ordre concret (objecte, després índex, després referència). Un sincronitzador els puja segons el seu propi criteri i velocitat. Si treballes des de dues màquines, el sincronitzador pot combinar un .git/index d'una amb les referències de l'altra, o crear fitxers del tipus main (conflicted copy 2026-07-28).lock.

El resultat és un repositori en un estat que Git mai no hauria pogut produir.

I el més irònic: no cal en absolut. Git ja és un sistema de sincronització distribuït. Per tenir el projecte en dues màquines, la resposta és un remot, no Dropbox.

Si de debò necessites que un repositori hi visqui, l'única manera segura és que sigui un repositori nu (--bare) usat com a remot, al qual mai no s'escriu des de dos llocs alhora. Tot i així, git bundle (apartat 7) és millor idea.

Si la Carla treballa a Windows 11 i pateix errors intermitents:

I a Git for Windows, un ajust que redueix problemes amb antivirus i amb sistemes de fitxers lents:

git fsck (file system check) recorre la base d'objectes, verifica que el contingut de cada objecte coincideix amb el seu hash, i comprova que totes les referències entre objectes es resolen.

Opcions útils:

Aquesta és la taula que evita el pànic innecessari.

La regla d'or per llegir fsck:

Si això no torna res, el teu repositori està sa. Punt. Tot el que hagis vist era soroll.

Tres línies alarmants en aparença, zero problemes. Són les restes del reset --hard de la setmana passada i d'un git add que no es va arribar a confirmar. Un repositori actiu sempre té això.

Aquí sí que hi ha feina. Una referència trencada i un objecte illegible, amb l'arbre que el necessita identificat. És l'apartat 4.

Aquest missatge, per a un hash que saps que existia, és la confirmació que l'objecte ha desaparegut.

o

No has perdut res. I la raó és conceptualment important:

L'índex és una memòria cau derivada. No conté informació única: és una foto de què hi hauria d'haver al pròxim commit, reconstruïble enterament a partir de HEAD i del directori de treball.

Per això la reparació és de les més agraïdes de Git:

L'única cosa que es perd és què estava preparat amb git add: després de la reconstrucció, totes les teves modificacions apareixen com a no preparades. Els canvis en si són intactes, perquè viuen als fitxers del disc, no a l'índex.

Un matís important: fes servir git reset (--mixed), mai git reset --hard. El primer reconstrueix l'índex i deixa el directori de treball en pau; el segon s'enduria per davant totes les teves modificacions (lliçó 09-02).

Si a més tenies un conflicte de fusió a mitges, la informació de les etapes de l'índex (:1:, :2:, :3: de la lliçó 03-05) sí que es perd, i cal refer la fusió:

Ja vist a la lliçó 09-01, aquí en la seva versió completa. Els forrellats són fitxers .lock que Git crea abans d'escriure i esborra en acabar:

El procediment:

Un cas especial que mereix cura: .git/config.lock. Si Git va morir escrivint la configuració, el fitxer .git/config pot haver quedat truncat. Comprova-ho abans d'esborrar el forrellat:

Si està trencat, la configuració local és el més fàcil de refer a mà de tot el repositori.

Què és. El fitxer refs/heads/GT-241 conté un hash que no correspon a cap objecte existent. Recorda que una branca són 41 bytes de text (lliçó 03-01):

Confirmat: la referència apunta al buit.

Reparació A: el reflog de la branca. És la millor opció, perquè conserva història:

Prova les entrades de dalt a baix fins a trobar-ne una de vàlida:

Has perdut l'últim commit, però recuperes la branca. Molt millor que res.

Reparació B: packed-refs. Les referències també viuen consolidades en un fitxer (lliçó 08-06):

De vegades la versió empaquetada és vàlida encara que la solta estigui trencada. Esborrant la solta, Git fa servir l'empaquetada:

Reparació C: el remot.

Reparació D: si la branca no importa, esborrar-la.

I la neteja massiva, quan hi ha moltes referències trencades:

Aquest és el cas seriós.

Primer pas, el diagnòstic exacte:

Zero bytes: escriptura interrompuda. És el patró típic de disc ple o tall de llum.

La reparació que gairebé sempre funciona: portar-lo d'un altre clon.

Aquesta és la idea central de la lliçó i l'apartat 5 la desenvolupa. Els objectes de Git són idèntics a tot arreu: el mateix contingut produeix el mateix hash i el mateix fitxer comprimit. Si el Bruno té aquell commit, el seu objecte serveix exactament igual.

Si l'altre clon el té empaquetat en lloc de solt, cal extreure'l:

Si el hash resultant coincideix amb el que faltava, la reparació és exacta. I no pot no coincidir: el hash es calcula del contingut, així que si en surt un altre, el contingut no era el mateix (lliçó 01-04).

Per a un objecte de tipus tree o commit, el mateix procediment amb -t tree / -t commit i el contingut exacte que dona cat-file -p al clon sa.

Si l'objecte era un packfile danyat:

Un packfile trencat és pitjor, perquè conté milers d'objectes i les cadenes de delta depenen les unes de les altres (lliçó 08-06). Es pot intentar extreure el que és salvable:

Però siguem clars: amb un packfile danyat, la resposta correcta gairebé sempre és reclonar (apartat 8). Extreure objectes d'un pack trencat és un exercici d'arqueologia que rarament compensa quan hi ha un clon sa a un git clone de distància.

HEAD és un fitxer de text d'una línia (lliçó 03-01):

El que hauria de contenir:

El que pot haver passat:

Si no queda cap branca vàlida, el reflog de HEAD continua sent text pla i llegible encara que Git no funcioni:

És el fitxer més fàcil de reparar, perquè el seu contingut és trivial de refer:

Si està truncat, edita'l (aquí sí, amb un editor de text: config és text pla per disseny i Git no el verifica amb hashos) o reconstrueix l'essencial:

Aquí hi ha la idea que converteix aquesta lliçó en una cosa manejable, i que tanca el cercle del mòdul 1.

En un sistema centralitzat, el servidor és un punt únic de fallada: si es corromp, s'ha corromput el projecte. A Git, cada clon conté tot l'historial. L'Ana, el Bruno, la Carla, el Diego i el servidor tenen cinc còpies completes de la base d'objectes.

Conseqüència pràctica: quan el teu repositori es corromp, la pregunta correcta no és «com el reparo?» sinó «què tinc jo que no tingui ningú més?».

GT-241 no té upstream: existeix només en aquesta màquina. És l'única cosa que cal salvar.

Amb aquestes quatre respostes ja saps exactament quant val la reparació. Si la resposta és «res, tot està publicat», reclonar triga dos minuts i és la solució perfecta.

I si el problema és del servidor, la direcció s'inverteix: qualsevol clon de l'equip el pot reconstruir.

--mirror copia totes les referències tal qual: branques, etiquetes, notes. És la manera correcta de duplicar un repositori nu.

El procediment complet, quan has decidit reclonar però tens coses locals a salvar.

Encara que vagis a reclonar. Costa deu segons i és l'única cosa que impedeix que un error durant el rescat sigui definitiu.

git bundle empaqueta commits en un sol fitxer que funciona com un remot. És l'eina correcta per a això, i funciona fins i tot si el repositori està parcialment danyat (mentre els objectes implicats estiguin sans).

Si a més tens canvis sense confirmar, treu-los a part:

Si git bundle falla perquè el repositori està massa danyat, la via bruta també serveix:

Es perd l'historial de les branques locals, però es conserva el contingut, que sol ser el que importava.

Les branques locals han tornat, amb tots els seus commits.

Si no hi ha errors i tota la teva feina hi és:

No esborris la còpia fins que ho hagis verificat. És l'única regla que importa d'aquest apartat.

Reprenent la lliçó 08-06:

A més de millorar el rendiment, manté la base d'objectes ordenada i redueix el nombre de fitxers solts exposats a escriptures interrompudes.

I una comprovació periòdica, que en un repositori normal triga segons:

I una configuració que fa que Git verifiqui els objectes en rebre'ls, detectant la corrupció en el moment en lloc de mesos després:

Costa una mica de temps a cada fetch i a canvi impedeix que un objecte mal format entri al teu repositori. Al servidor, receive.fsckObjects és directament obligatori.

Un bundle és un únic fitxer amb tot el que li demanis, que funciona com un remot. És portàtil, verificable i no depèn de cap servei.

I còpies incrementals, si el repositori és gran:

Un guió de còpia setmanal:

Per què un bundle és millor que copiar .git amb cp:

1. Mai un repositori en una carpeta sincronitzada pel núvol. La causa número u. Fes servir un remot.

2. Mai .git en un volum de xarxa si ho pots evitar. Clona en local i publica.

3. Exclou les teves carpetes de projectes de l'antivirus a Windows.

4. Vigila l'espai al disc. Un df -h de tant en tant.

5. git maintenance start als repositoris de treball.

6. transfer.fsckObjects true per detectar la corrupció quan entra.

7. Publica les teves branques. Una branca publicada és a dues màquines. És la millor còpia de seguretat i la més barata.

8. git bundle setmanal del que només tens tu.

9. No matis processos de Git amb kill -9, especialment durant gc o repack.

10. No editis fitxers de .git a mà (tret de config, que és text per disseny). Fes servir git update-ref, git symbolic-ref, git config.

La decisió més important de la lliçó, i la que més temps estalvia.

Reclonar és la resposta correcta quan:

• El repositori està completament publicat (res local sense enviar). Aleshores reclonar no té cap cost.
• Hi ha un packfile danyat. Extreure objectes d'un pack trencat rarament compensa.
• git fsck torna més d'un grapat d'errors.
• La corrupció reapareix després de reparar-la: hi ha una causa de fons (disc, núvol, antivirus) que no has resolt.
• Portes més de trenta minuts intentant reparar-lo. El cost d'un git clone és de minuts; el d'una tarda d'arqueologia, no.

Val la pena intentar la reparació quan:

• El problema és l'índex, un forrellat, HEAD o config. Són minuts i no es perd res.
• És una referència trencada i el reflog o packed-refs la resolen.
• Falta un objecte i saps d'on portar-lo.
• Tens feina local important sense publicar i necessites extreure-la abans de reclonar (apartat 6).

En forma d'arbre:

I la frase que resumeix la lliçó:

Un repositori Git danyat no és un problema de dades: és un problema de logística. Les dades gairebé sempre són en un altre lloc. La teva feina consisteix a identificar què és exclusivament teu, salvar-ho, i portar la resta d'on estigui sa.

Error 1: espantar-se amb els dangling de git fsck. Són completament normals en qualsevol repositori actiu. Filtra amb grep -v "^dangling" i mira si queda alguna cosa.

Error 2: donar per corrupte el que és un disc ple. df -h és la primera ordre. Reparar amb el disc al 100 % no pot funcionar.

Error 3: tenir el repositori a Dropbox, OneDrive o iCloud. És la causa número u de corrupció real, i no cal en absolut: Git ja sincronitza.

Error 4: git reset --hard per reparar un índex corrupte. rm .git/index && git reset reconstrueix sense tocar els teus fitxers; amb --hard els perdries tots.

Error 5: editar fitxers de .git amb un editor de text. Tret de config, fes servir les ordres: git update-ref, git symbolic-ref, git config.

Error 6: reparar sense haver fet una còpia. cp -a costa deu segons i evita que un error durant el rescat sigui definitiu.

Error 7: passar hores reparant un repositori que està íntegrament publicat. Comprova primer què tens que no tingui ningú més. Si la resposta és «res», reclona.

Error 8: fer servir cp -a .git com a còpia de seguretat «oficial». Val per a una emergència, però pot copiar un estat a mitges. git bundle és coherent i verificable.

Error 9: esborrar el repositori trencat abans de verificar el nou. Verifica amb git fsck i comprova que tota la teva feina hi és; després esborra.

Consell 1: aprèn el filtre de fsck. git fsck --full --no-progress 2>&1 | grep -vE "^(dangling|notice)". Si no torna res, estàs sa.

Consell 2: git bundle create ... --all setmanal. Un fitxer, verificable, restaurable amb git clone.

Consell 3: transfer.fsckObjects true a la configuració global. Detecta la corrupció quan entra, no mesos després.

Consell 4: publica les teves branques. És la còpia de seguretat més barata i la que més vegades salva.

Consell 5: l'índex és una memòria cau. Perdre'l no té importància; recordar-ho evita molt pànic innecessari.

Consell 6: posa't un límit de temps. Trenta minuts de reparació i, si continua trencat, reclona. El clon en triga dos.

1. Crea un repositori amb deu commits, una branca amb tres commits propis i un git add sense confirmar.
2. Provoca objectes penjants: un reset --hard HEAD~3, un commit --amend i un branch -D.
3. Executa git fsck --full i compta quantes línies torna.
4. Aplica el filtre del consell 1 i comprova que no queda res. Explica per què el repositori està sa malgrat les línies anteriors.
5. Identifica, entre els penjants, quin correspon al git add sense confirmar i recupera'l amb git cat-file -p.

Sobre un repositori de proves (mai sobre un de real):

1. Corromp l'índex: printf 'brossa' > .git/index. Executa git status i anota l'error. Repara'l i explica per què no es perd res.
2. Trenca una referència: echo "0000000000000000000000000000000000000000" > .git/refs/heads/GT-241. Executa git fsck i repara-la amb el reflog.
3. Trenca HEAD: echo "ref: refs/heads/inexistent" > .git/HEAD. Diagnostica i repara amb git symbolic-ref.
4. Buida un objecte solt: localitza'n un amb find .git/objects -type f i trunca'l amb : > <fitxer>. Executa git fsck --full i observa l'error.
5. Repara el punt 4 des d'un clon sa que hauràs fet abans de trencar res.
6. Després de cada reparació, executa git fsck --full filtrat i confirma que està net.

1. Munta un remot local amb git init --bare i clona'l.
2. Al clon, publica dos commits a main i crea dues branques locals sense publicar amb tres commits cadascuna. Afegeix un desament temporal i algun canvi sense confirmar.
3. Fes l'inventari de l'apartat 5: quines branques no tenen upstream, quins commits no són al remot.
4. Crea un bundle amb tot el que és local i verifica'l.
5. Esborra el clon sencer (simulant corrupció irreparable) i torna a clonar.
6. Reincorpora les dues branques des del bundle i comprova que els sis commits hi són.
7. Explica què s'ha perdut i què no, i com ho hauries evitat publicant les branques.

Solució 1:

Nou línies d'aspecte preocupant.

Zero errors. El repositori està perfectament sa.

La raó: dangling significa «aquest objecte existeix i és llegible, però cap referència no hi arriba». És exactament el resultat esperat d'un reset, un --amend i un branch -D: els commits continuen allà (per això són recuperables, lliçó 09-04) però ja no pengen de cap branca. És el contrari d'un problema: és la prova que la xarxa de seguretat funciona.

Els errors de debò comencen per error:, missing o broken link, i aquí no n'hi ha cap.

Solució 2:

Res perdut. La modificació continuava al fitxer del disc; l'índex només era la foto de què entraria al pròxim commit, i es reconstrueix des de HEAD més el directori de treball. És una memòria cau.

Reparada, i amb el seu commit. El reflog conservava el hash correcte perquè el fitxer de reflog és independent del fitxer de referència.

Git no falla, però es pensa que és en una branca que no existeix: git log no mostra res i un commit crearia una branca nova.

Git es nega a operar: no pot llegir un objecte que necessita.

El hash coincideix, així que la reparació és demostrablement exacta. No pot ser d'altra manera: el nom de l'objecte és el hash del seu contingut (lliçó 01-04), de manera que si el hash surt igual, el contingut és idèntic byte a byte. Aquesta propietat és la que fa que reparar un repositori Git des d'un altre clon sigui segur i verificable.

Solució 3:

Sis commits, dues branques, un desament temporal i dos canvis existeixen únicament en aquesta màquina. Aquest és exactament el valor de la reparació.

Només el que és publicat.

Els sis commits i les dues branques, amb els seus hashos originals.

El que s'ha perdut:

• La pila de desaments temporals com a tal. El contingut s'ha reaplicat des del pedaç, però l'entrada stash@{0} no existeix. (Un bundle amb --all hauria inclòs refs/stash.)
• Tot el reflog, que és local i no viatja (lliçó 09-04). El clon nou té tres entrades.
• Les branques de seguiment antigues i la configuració local del repositori.

El que no s'ha perdut: ni un sol commit, ni un sol canvi.

Com s'hauria evitat: publicant les branques.

Amb les dues branques publicades, l'inventari del pas 3 hauria sortit buit, i tota aquesta lliçó s'hauria reduït a rm -rf feina && git clone. Dos segons de push davant de vint minuts de rescat.

La corrupció d'un repositori Git espanta molt més del que costa.

• La majoria dels missatges alarmants no són corrupció: un forrellat orfe, un disc ple, un problema de permisos o de propietat. Descarta-ho primer amb df -h i ls -ld .git.
• Les causes reals vénen gairebé sempre de fora de Git: un repositori en una carpeta sincronitzada amb el núvol (la número u), un disc ple, un tall de llum, un volum de xarxa, un antivirus. Els objectes de Git són immutables i porten la seva pròpia verificació; Git rarament es trenca sol.
• git fsck es llegeix filtrant el soroll. Els objectes dangling són completament normals —són les restes de cada reset, rebase i --amend— i la seva presència és la prova que la xarxa de seguretat de la lliçó 09-04 funciona. El que és greu comença per error:, missing o broken link.
• Les reparacions, de menor a major: l'índex és una memòria cau derivada i es reconstrueix amb rm .git/index && git reset sense perdre res; els forrellats s'esborren després de comprovar processos; una referència trencada es repara amb el reflog, packed-refs o el remot; HEAD amb git symbolic-ref; un objecte illegible portant-lo d'un altre clon, amb la garantia que si el hash coincideix, la reparació és exacta.
• El model distribuït és la xarxa de seguretat. Cada clon de l'equip és una còpia gairebé completa. La pregunta correcta davant d'un repositori danyat no és «com el reparo?» sinó «què tinc jo que no tingui ningú més?», i es respon amb git for-each-ref i git log --branches --not --remotes.
• El rescat es fa amb git bundle: empaquetar el que és local en un fitxer, reclonar, i reincorporar-ho amb git fetch <bundle>. I sempre amb un cp -a previ i una verificació posterior abans d'esborrar res.
• Prevenció: res de repositoris al núvol ni en volums de xarxa, git maintenance start, transfer.fsckObjects true, git bundle periòdic i —el que més rendeix— publicar les branques.
• I el criteri: si tot està publicat, reclona. Triga dos minuts i és la resposta correcta. Reserva la reparació per a l'índex, els forrellats, HEAD i les referències, o per extreure feina local abans de reclonar.

Amb això, el mòdul ha cobert els quatre problemes que anunciava el tancament del mòdul 8: el reset --hard desafortunat, l'embolic amb el remot, la branca esborrada i el repositori que es nega a funcionar.

Queda el que és transversal. Perquè moltes vegades el problema no és que Git estigui trencat ni que hagis perdut alguna cosa, sinó que Git està fent alguna cosa que no entens: un fitxer que s'ignora quan no hauria de ser així, una configuració que ve d'un lloc que no sabies que existia, un push que falla per raons opaques, un canvi de comportament que ningú no recorda haver introduït. Per a això hi ha una caixa d'eines pròpia —traces, lampisteria, check-ignore, check-attr, ls-files— i, sobretot, un mètode.

Continua a la lliçó 09-06: Tècniques Avançades de Depuració.