El mòdul anterior va acabar amb una llista de desastres anunciats: el reset --hard sobre tres dies de feina, el commit a la branca equivocada, el pull sobre una branca divergida, la branca esborrada que sí que importava, el .git/index corrupte. Aquest mòdul és el manual per quan passen.

I passen sempre en el pitjor moment. Són les set de la tarda d'un divendres, la Carla ha d'entregar GT-241 abans del tancament, executa una ordre que no acaba d'entendre i el terminal respon una cosa que no havia vist mai. El primer que fa la majoria de la gent en aquell moment —provar ordres a l'atzar tretes d'una resposta de fòrum— és exactament el que converteix un problema petit en un de gros.

Aquesta lliçó és dues coses. Primer, un protocol de calma: què fer abans de tocar res. I després, el catàleg d'urgències: una taula gran de símptoma → causa probable → on es resol, que funciona com a índex de la resta del mòdul. Els casos trivials es resolen aquí mateix; els que tenen substància es remeten a la seva lliçó.

Comencem per la idea que sosté tota la resta, perquè és la que permet treballar amb calma.

1. La idea que ho sosté tot: a Git gairebé res no es perd
2. El protocol de calma: quatre ordres abans de tocar res
3. La còpia de seguretat de deu segons
4. El catàleg d'urgències
5. Els casos trivials, resolts aquí
6. Com llegir un missatge d'error de Git
7. Què NO fer mai en estat de pànic

Recupera el model de dades de la lliçó 01-04. Un commit és un objecte immutable a .git/objects, identificat pel hash del seu contingut. Una branca és un fitxer de 41 bytes que conté un hash (lliçó 03-01). I la relació entre totes dues coses és la clau:

Els commits no pertanyen a les branques. Les branques simplement apunten a commits.

D'aquí es dedueix el que fa habitable aquest mòdul: quan esborres una branca, no esborres cap commit. Quan fas reset --hard, no esborres cap commit. Quan un rebase surt malament, els commits originals continuen allà. L'única cosa que ha canviat és que cap referència no els apunta: s'han tornat inassolibles.

C i D continuen existint, byte a byte, a .git/objects. Ningú no els ha tocat. Simplement main ja no hi arriba, i per això git log no els mostra. Recuperar-los és qüestió de tornar a apuntar-hi alguna cosa, i per a això existeix el reflog, que és el tema de la lliçó 09-04.

Els objectes inassolibles sí que acaben desapareixent, però no immediatament: git gc (lliçó 08-06) els elimina quan fa més de dues setmanes que no tenen referències, i les entrades del reflog caduquen als 90 dies (30 per al que és inassolible). A la pràctica, tens setmanes per recuperar qualsevol commit.

Tot l'anterior es recolza en una condició: que la feina hagi arribat a ser un commit. El que mai no es va confirmar no és a la base de dades d'objectes i, per tant, no hi ha res a recuperar.

Aquesta taula és el mapa mental de tot el mòdul. Fixa't en el detall de la segona fila: git add ja desa el contingut a la base de dades. Un fitxer que vas preparar i després vas destruir amb git checkout és recuperable, encara que no el confirmessis mai.

D'aquí surt el consell més rendible del mòdul, i no és una ordre:

Confirma aviat i sovint. Un commit lleig amb el missatge "wip" et protegeix de tot el que ve a les cinc lliçons següents. Ja ho netejaràs amb rebase -i (lliçó 05-02) abans de publicar.

Quan alguna cosa va malament, la temptació és actuar. Resisteix-la. Les quatre ordres següents no modifiquen res, triguen tres segons i, en la majoria dels casos, el diagnòstic ja està fet quan acabes de llegir-les.

És l'ordre més infravalorada de Git. No només diu quins fitxers han canviat: diu en quin estat es troba el repositori i, molt sovint, et suggereix literalment la sortida.

Aquí hi ha tot: quina operació està a mitges, per on va, i les tres maneres de sortir-ne. Molta gent en pànic no executa git status precisament quan més ho necessita.

Els estats que pot anunciar:

La forma de l'historial visible des d'on ets ara. Serveix per a dues coses: confirmar que ets on et penses que ets, i veure si el commit que busques continua sent assolible.

I una variant que convé tenir a mà quan sospites que et falta alguna cosa:

Si el commit que busques apareix a --all però no al log normal, no s'ha perdut: és en una altra branca. Aquest és el cas més freqüent de tots, i no requereix recuperar res.

El registre de per on ha passat HEAD. És la caixa negra del repositori i contesta la pregunta "què dimonis acabo de fer?".

Es llegeix de baix a dalt en ordre cronològic. L'entrada HEAD@{0} és sempre l'última cosa que ha passat, i aquí diu clarament que hi va haver un reset que va deixar enrere dos commits. Els hashos d'aquells commits continuen escrits allà, i això és exactament el que fa possible recuperar-los.

El reflog és el tema complet de la lliçó 09-04. Aquí n'hi ha prou d'executar-lo i llegir-lo: en el 80 % dels ensurts, la resposta és en aquestes vint línies.

Comprova la integritat de la base d'objectes. No l'executis per rutina: és lent en repositoris grans i la seva sortida espanta més del que hauria (els objectes dangling són normals i inofensius). Reserva aquest pas per quan Git es negui a fer coses bàsiques o doni errors sobre objectes. La seva interpretació completa és a la lliçó 09-05.

Val la pena tenir-lo com a àlies (lliçó 06-04):

Tres segons, zero modificacions, i gairebé sempre el diagnòstic complet.

Si després del protocol de calma la situació continua sense ser clara, fes una còpia abans d'intentar res. És la diferència entre "tinc un problema" i "tinc un problema i a més he empitjorat les coses".

A Windows (PowerShell):

Tres detalls importants:

• cp -a (o -R preservant enllaços) copia el directori sencer, .git inclòs. Això és el que fa que sigui una còpia real i no un clon parcial.
• No facis servir git clone per a això. Un clon no s'emporta el reflog, ni els desaments temporals, ni les branques no publicades, ni els canvis sense confirmar. Precisament el que necessites conservar.
• Fes-ho abans d'executar qualsevol ordre que comenci per git reset, git clean, git rebase o git push --force.

Quan el problema estigui resolt, esborra la còpia. Quan no ho estigui, agrairàs tenir-la.

Per a còpies de seguretat de debò, amb format i no amb cp, hi ha git bundle, que es veu a la lliçó 09-05.

Aquesta és la taula central de la lliçó. Busca't a la columna de l'esquerra.

Un consell d'ús: abans de buscar a internet, busca en aquesta taula. Les respostes de fòrum solen estar descontextualitzades i moltes comencen per git reset --hard, que és exactament el que no has d'executar sense entendre-ho.

Aquests no necessiten lliçó pròpia. Són problemes d'un minut, sempre que sàpigues quina és l'ordre.

L'Ana porta mitja hora tocant app.js i descobreix que és a main, no a GT-241.

No has perdut res. Els canvis sense confirmar no pertanyen a cap branca: viuen al directori de treball i a l'índex. Canviar de branca se'ls emporta amb tu.

Els canvis són intactes, ara a la branca correcta, i main no s'ha mogut.

Si la branca ja existeix:

Git s'emporta els canvis sense més, excepte si algun dels fitxers modificats difereix entre les dues branques. En aquest cas avisa:

La sortida és el stash de la lliçó 05-04:

El Bruno ha fet dos commits de GT-247 directament sobre main, i main encara no s'ha publicat amb ells.

No has perdut res. Els commits existeixen; l'única cosa mal posada és a què apunta cada branca. La recepta és: marcar aquí, i tornar la branca al seu lloc.

L'ordre importa: crea primer la branca, i només després mou main. Així els commits mai no deixen de ser assolibles i el reset --hard és completament segur. (Si t'equivoques d'ordre, tampoc no passa res: per a això hi ha el reflog de la 09-04. Però fes-ho bé.)

Si els commits ja estaven publicats a main, la resposta no és aquesta sinó git revert (lliçó 05-06), perquè estaries reescrivint historial públic.

Variant: si són alguns commits solts i no els últims, l'eina és git cherry-pick (lliçó 05-03).

La Carla ha configurat el portàtil nou i ha confirmat com a [email protected].

Per a l'últim commit, sense publicar:

Un matís que confon molta gent: Git desa dues identitats per commit.

--author només toca el primer. Per al segon, Git fa servir user.email en el moment de crear el commit, així que n'hi ha prou d'haver corregit la configuració abans de l'--amend. Si necessites forçar-ho:

I la prevenció, que val més que la cura (lliçó 01-05):

Amb això, un repositori sense user.email propi dona error en lloc d'inventar-se una identitat a partir del nom de la màquina. És la configuració que evita aquest problema per sempre.

Si són diversos commits, cal reescriure: git rebase -i amb exec (lliçó 05-02) per a uns quants, o git filter-repo --mailmap (lliçó 08-05) per a un historial sencer. I sempre amb la regla d'or al davant: només si no està publicat.

--no-edit conserva el missatge tal com és. El commit anterior se substitueix per un de nou amb el mateix missatge i el fitxer inclòs.

El hash canvia. Si ja l'havies publicat, això reescriu historial: no ho facis, i afegeix-hi un commit nou al seu lloc. És exactament la situació de la lliçó 08-02, on la solució elegant és git commit --fixup + rebase --autosquash abans de publicar.

Comprovació prèvia útil, per no incloure-hi res de més:

Què és. Git crea .git/index.lock abans de modificar l'índex i l'esborra en acabar. És un forrellat perquè dos processos no escriguin alhora. Si el procés va morir —el vas tancar amb Ctrl+C, es va penjar l'editor, l'IDE el va matar—, el fitxer es queda orfe.

El procediment correcte, en aquest ordre:

La causa més habitual amb diferència és un IDE (VS Code, IntelliJ, Eclipse) executant git status en segon pla just quan tu llances una ordre. Si et passa sovint, no és un problema de Git: és una cursa entre dos clients.

No esborris .git/index.lock sense comprovar el pas 1. Si de debò hi ha un altre procés escrivint, treure-li el forrellat pot corrompre l'índex —que és justament el que tracta la lliçó 09-05—. Amb la comprovació feta, esborrar-lo és completament inofensiu.

Hi ha altres forrellats amb la mateixa lògica i el mateix tractament: .git/HEAD.lock, .git/refs/heads/main.lock, .git/shallow.lock.

Què és. Des de Git 2.35, Git es nega a operar en un repositori el propietari del qual, al sistema de fitxers, no ets tu. És una mesura de seguretat, no una fallada: un repositori aliè pot contenir hooks (lliçó 06-01) o configuració que s'executen en llançar ordres.

Els escenaris típics: WSL accedint a un disc de Windows, un contenidor Docker amb un volum muntat, un disc extern formatat en un altre sistema, o un repositori clonat amb sudo.

I el que no has de fer, encara que ho trobis a internet:

Abans d'afegir l'excepció, planteja't si la propietat és correcta. Si el repositori és teu i apareix com a de root, probablement el vas clonar amb sudo i la solució real és:

No és un error. És Git informant que HEAD apunta directament a un commit i no a una branca (lliçó 03-02). S'hi arriba amb git checkout <sha>, amb git switch --detach, en inspeccionar una etiqueta, durant un bisect o enmig d'un rebase.

Dos casos:

A. No has fet commits estant-hi. Torna i prou:

B. Has fet commits estant-hi. Aquest és el cas que cal saber, perquè aquests commits no són a cap branca i desapareixeran de la vista tan bon punt et moguis:

I si ja t'havies mogut i els has perdut de vista: no passa res, el reflog els té (lliçó 09-04).

Diagnòstic en tres ordres, de menys a més (lliçó 04-03):

Si això funciona i el push no, el problema és la URL del remot, no la clau:

Si no funciona:

I si continua fallant, la traça detallada, que és terreny de la lliçó 09-06:

Causes freqüents en ordre de probabilitat: la clau pública no està registrada al servidor; l'agent no s'està executant (típic després de reiniciar); permisos incorrectes a ~/.ssh (ha de ser 700, i les claus privades 600); o hi ha diverses claus i SSH ofereix la que no toca (s'arregla amb un bloc Host a ~/.ssh/config).

La mecànica de resolució és completa a la lliçó 03-05. L'única cosa que cal aquí és la sortida d'emergència, perquè en pànic no es recorda:

--abort torna el repositori exactament a l'estat previ a l'operació. És segur i no perd res del que hi havia abans de començar (sí que perd la feina de resolució que haguessis fet durant el conflicte).

Si --abort falla perquè tenies canvis sense confirmar barrejats, el reflog i ORIG_HEAD són la sortida, i això és la lliçó 09-04.

Git té fama de missatges críptics i en part és merescuda, però han millorat moltíssim. Val la pena saber-los llegir, perquè gairebé sempre contenen la solució.

L'anatomia típica:

Tres regles pràctiques:

1. fatal: és tranquil·litzador. Significa que Git s'ha negat a actuar. Res no s'ha trencat.
2. Les línies hint: són la documentació al lloc exacte. Es poden silenciar amb advice.*, i molta gent ho fa sense adonar-se'n en copiar configuracions alienes. Comprova-ho amb git config --get-regexp '^advice\.'.
3. El missatge anomena els fitxers implicats. Gairebé sempre acota el problema a l'instant.

I un ajust que ajuda a llegir, si treballes en anglès forçat per defecte:

Buscar el missatge en anglès dona moltíssims més resultats útils que buscar-lo traduït.

Tanca la lliçó la llista negra. Tot el que segueix ha convertit problemes petits en desastres reals.

1. Copiar i enganxar ordres d'internet sense entendre-les. Especialment si comencen per git reset --hard, git push --force, git clean -fdx o rm -rf .git. La resposta que et serveix a tu depèn d'un context que el fòrum no coneix.

2. git push --force. Mai en pànic, i gairebé mai fora d'ell. Si ha de ser, --force-with-lease (lliçons 04-05 i 09-03), i només sobre una branca que sigui teva.

3. git clean -fdx "per deixar-ho net". Esborra de debò, i sense xarxa de seguretat: els fitxers sense seguiment no són a la base de dades. Executa sempre git clean -n abans (lliçó 09-02).

4. Esborrar .git. És el repositori sencer: tot l'historial, totes les branques, el reflog. No és "la configuració".

5. Tornar a clonar a sobre del directori amb problemes. De vegades reclonar és la resposta correcta (lliçó 09-05), però primer es copia i es rescata el que és local: branques sense publicar, desaments temporals, canvis en curs.

6. Encadenar ordres sense mirar el resultat de cadascuna. Després de cada pas: git status i git log --oneline -5.

7. Executar git gc --prune=now o git reflog expire --expire=now. És l'única cosa d'aquesta llista que destrueix la xarxa de seguretat de tot el mòdul (lliçó 08-06). Si hi ha alguna cosa a recuperar, aquestes ordres ho fan impossible.

8. Callar. Si has forçat alguna cosa sobre una branca compartida, o has esborrat alguna cosa del servidor, avisa l'equip en aquell moment. Cinc minuts després és un avís; cinc hores després és un trencaclosques per a tothom.

Error 1: actuar abans de diagnosticar. El protocol de calma —status, log --graph, reflog— costa tres segons i resol la majoria dels casos sense tocar res.

Error 2: no llegir el que diu git status. És l'ordre que més informació dona i la primera que s'oblida en pànic. Sovint conté literalment l'ordre que necessites.

Error 3: creure que un reset --hard o un branch -D han destruït commits. No ho han fet. Els commits continuen a .git/objects i el reflog sap on són (09-04).

Error 4: confiar que tot és recuperable, inclòs el que no s'ha confirmat. No ho és. El que mai no va ser un commit (ni un add, ni un stash) no és enlloc.

Error 5: fer servir git clone com a còpia de seguretat d'emergència. No s'emporta el reflog, ni els desaments temporals, ni les branques locals, ni el que no s'ha confirmat. Fes servir cp -a del directori complet.

Error 6: esborrar .git/index.lock sense comprovar si hi ha un altre procés. Amb la comprovació és inofensiu; sense ella pot corrompre l'índex.

Error 7: silenciar els hint: de Git. Són la millor documentació contextual que existeix, escrita just quan la necessites.

Error 8: safe.directory '*'. Desactiva una protecció real de seguretat a tot arreu. Afegeix l'excepció concreta, o arregla la propietat del directori.

Consell 1: confirma aviat i sovint. Un commit "wip" cada mitja hora fa que les cinc lliçons següents gairebé mai no et calguin. L'historial es neteja després amb rebase -i.

Consell 2: defineix l'àlies git panic. El dia que el necessitis no recordaràs les tres ordres.

Consell 3: cp -a abans de res seriós. Deu segons que compren tranquil·litat per experimentar.

Consell 4: user.useConfigOnly true a la configuració global. Elimina per sempre el commit amb l'autor equivocat.

Consell 5: busca els missatges d'error en anglès. Deu vegades més resultats útils.

Consell 6: quan passi alguna cosa rara amb una branca compartida, avisa immediatament. El cost social d'avisar tard és molt més gran que el d'avisar.

1. Crea un repositori amb app.js i tres commits a main. Simula el remot amb un clon --bare local i publica main.
2. Sense canviar de branca, fes dos commits més que haurien d'haver anat a GT-247.
3. Aplica el procediment de l'apartat 5.2 i deixa main com al remot i GT-247 amb els dos commits.
4. Demostra amb git log --oneline --all --graph que cap commit no s'ha perdut.
5. Comprova al reflog quins moviments han quedat registrats.

1. En un repositori nou, configura deliberadament malament user.email (ningu@localhost) i fes un commit que inclogui només index.html, oblidant estils.css.
2. Comprova l'autor amb git log -1 --format='%an <%ae>'.
3. Corregeix la configuració, afegeix el fitxer oblidat i arregla l'autor en un sol --amend.
4. Comprova que el hash del commit ha canviat i explica per què això el faria inacceptable si ja estigués publicat.
5. Activa user.useConfigOnly true i comprova què passa en intentar confirmar en un repositori sense identitat configurada.

1. Crea un repositori amb sis commits i una branca GT-241 amb dos commits propis.
2. Estant a GT-241, executa git reset --hard HEAD~2.
3. Sense recuperar res encara, executa els quatre passos del protocol de calma i escriu què et diu cadascun.
4. Identifica al reflog el hash exacte del commit que era la punta de GT-241 abans del reset.
5. Crea una branca rescat sobre aquest hash i comprova que la feina és intacta.
6. Repeteix l'experiment, però aquesta vegada amb un fitxer modificat i sense confirmar en el moment del reset --hard. Explica la diferència.

Solució 1:

main és on el remot, GT-247 té els seus dos commits, i els cinc commits continuen existint. El reset --hard va ser segur perquè git branch GT-247 ja els mantenia assolibles.

Fixa't en HEAD@{1}: el reflog registra el reset i el hash des del qual es va sortir. Encara que haguessis oblidat el pas 2, 7d3a8f4 és allà escrit.

Solució 2:

El committer també s'ha corregit perquè l'--amend va crear l'objecte després d'arreglar user.email.

8f4c2a9 → 3f8a1d6. Un commit és immutable (lliçó 01-04): --amend no el modifica, en crea un de nou i mou la branca. Si l'original estigués publicat, qui el tingués baixat el continuaria tenint, la branca hauria divergit i el push seria rebutjat: exactament l'escenari de la lliçó 09-03.

Git es nega en lloc d'inventar-se usuari@nom-de-la-maquina. El problema de l'apartat 5.3 deixa de ser possible.

Solució 3:

Lectura: no hi ha cap operació a mitges i no hi ha res sense desar. Això és bona notícia: tot el que hi havia estava confirmat i, per tant, és a la base de dades.

Lectura: des d'aquí, els dos commits de GT-241 ja no són assolibles. git log no els veu. Això és el que provoca el pànic, i és només un problema de referències.

Lectura: allà hi ha tot. HEAD@{1} és la punta que hi havia abans del reset.

Lectura: Git confirma que el commit existeix i que ningú no l'apunta. Dangling aquí és exactament el que esperem (lliçó 09-05).

Feina intacta. Crear una branca és més segur que fer reset, perquè no mou res del que ja està bé: només afegeix un punter. És el patró que es generalitza a la lliçó 09-04.

Aquesta línia no és enlloc. No hi ha cap entrada de reflog que la registri, no hi ha cap objecte penjant que la contingui, git fsck no troba res. Mai no va arribar a la base de dades d'objectes.

I la variant que canvia el resultat completament:

Amb un simple git add, el contingut és recuperable. Aquesta és la frontera exacta entre el que Git pot salvar i el que no, i per això el consell de confirmar (o si més no preparar) sovint no és una mania d'estil: és la xarxa de seguretat.

Aquesta lliçó és l'índex del mòdul i, sobretot, el canvi d'actitud que fa que la resta funcioni.

• A Git gairebé res no es perd de debò. Els commits són objectes immutables que sobreviuen encara que cap referència no els apunti; esborrar una branca o moure un punter amb reset no destrueix res. El que és veritablement fràgil és el que mai no va arribar a la base de dades: els canvis sense confirmar i els fitxers sense seguiment.
• git add ja compta. El contingut preparat es desa com a blob i es pot rescatar. Confirmar és millor, però preparar ja és una xarxa.
• El protocol de calma —git status, git log --oneline --graph -20, git reflog -20 i, només si cal, git fsck— no modifica res, triga tres segons i resol la majoria dels ensurts abans de tocar una sola ordre destructiva.
• cp -a del directori complet és la còpia de seguretat d'emergència. Un clone no serveix: no s'emporta el reflog, ni els desaments temporals, ni el que és local.
• Els missatges de Git són millors del que la seva fama suggereix. fatal: significa que no s'ha fet res; les línies hint: solen contenir literalment la solució.
• Els casos trivials es resolen en una ordre: git switch -c per als canvis a la branca equivocada, git branch + reset --hard origin/x per als commits mal col·locats, commit --amend --author per a la identitat, --amend --no-edit per al fitxer oblidat, esborrar index.lock després de comprovar els processos, i safe.directory per a la propietat dubtosa.
• I la llista negra: res de --force, clean -fdx, rm -rf .git ni gc --prune=now en estat de pànic.

La resta del mòdul desenvolupa els casos que no caben en una fila de taula. Comencem pel més freqüent i pel que tanca una promesa pendent des de la lliçó 05-06: el mecanisme de git reset, els seus tres modes, què toca exactament cadascun, i com triar l'eina correcta segons si el que vols desfer està sense confirmar, confirmat sense publicar o ja publicat.

Continua a la lliçó 09-02: Desfent Canvis.