La lliçó anterior va acabar amb un exercici incòmode: un BREAKING CHANGE perfectament escrit va desaparèixer en integrar la branca amb squash merge, i l'eina de versionatge va publicar com a MINOR un canvi que trencava tots els consumidors. El missatge era impecable; el que va fallar va ser la política d'integració.

Aquesta lliçó resol aquesta qüestió i, amb ella, la que vam deixar deliberadament oberta a la lliçó 07-04: quan arriba el moment de fusionar una pull request, merge, squash o rebase? És probablement la discussió més recurrent i més religiosa de tots els equips que fan servir Git, i té resposta raonada —encara que no sigui la mateixa per a tots els projectes.

Però abans cal respondre una pregunta prèvia que gairebé ningú es fa: net per a què? Un historial no és una obra d'art. És una eina de treball amb usos concrets i mesurables. Un historial "bonic" que no serveix per a cap d'aquests usos no és un historial net: és decoració cara.

1. Per a què serveix realment un historial
2. El commit atòmic
3. Com arribar a commits atòmics: add -p i rebase -i
4. La decisió d'integració: merge, squash o rebase
5. Taula comparativa a fons
6. Quina política encaixa amb cada flux
7. Recomanació raonada per tipus de projecte
8. Netejar abans de publicar, no tocar el que s'ha publicat
9. Commits de fusió: quan aporten i quan són soroll
10. Historial lineal davant d'historial amb topologia
11. Els commits de reformatatge massiu i .git-blame-ignore-revs
12. Què significa que un historial sigui "bisecable"

Si no penses mirar mai enrere, qualsevol historial serveix. La qualitat de l'historial només es paga quan el consultes, i es consulta per a cinc coses molt concretes. Totes les coneixes ja del curs:

Fixa't que cap dels cinc demana un graf bonic. Demanen commits petits, autocontinguts, ben descrits i que funcionin. Aquest és l'objectiu real. La topologia —lineal o amb branques— és un mitjà, no una finalitat, i per això la discussió merge/squash/rebase només es pot resoldre preguntant quin d'aquests cinc usos importa més al teu projecte.

Definició de treball: un historial net és aquell en què qualsevol commit es pot entendre, provar, revertir i atribuir per separat.

Un commit atòmic és un commit que conté un canvi complet i només un. Les dues meitats de la definició importen igual:

• Complet: no deixa el projecte trencat. Compila, passa les proves, la funcionalitat que toca funciona.
• Només un: no arrossega canvis que no tenen a veure amb el seu propòsit.

El cas patològic clàssic, que tothom ha comès:

340 línies canviades a app.js per "afegir un filtre". A dins hi ha, amb tota seguretat: el filtre (30 línies), un reformatatge del fitxer sencer en desar amb l'editor (250 línies), un reanomenament de dues variables (20), una correcció d'una errada sense relació (5) i la pujada d'una dependència (el package.json).

Què hi perds, amb aquest commit:

• git blame sobre qualsevol línia d'app.js t'hi porta, encara que aquella línia només canviés de sagnat.
• Si el filtre té una fallada, git revert t'obliga a revertir també la pujada de la dependència.
• git bisect l'assenyalarà com a culpable, però el diff és tan gran que no hauràs avançat gens.
• El revisor no el pot avaluar: 340 línies de les quals 250 són soroll.

Hi ha un test molt simple, i enllaça amb la lliçó anterior: si no pots descriure el commit en un assumpte de 50 caràcters sense fer servir "i", no és atòmic. La incapacitat d'anomenar-lo és el símptoma.

L'objecció pràctica és real: "però jo no programo així, jo vaig tocant coses". Ningú programa en commits atòmics. Els commits atòmics es fabriquen després, amb dues eines que ja domines.

A la lliçó 02-04 vam veure git add -p per preparar canvis per fragments. Aquest és exactament el seu propòsit aquí: has tocat tres coses a app.js i en vols tres commits.

Respons y als fragments del filtre i n als altres, confirmes, i repeteixes. Recorda les tecles que més renten:

I una comprovació imprescindible abans de confirmar, perquè preparar per fragments permet crear un commit que no compila:

Aquest stash --keep-index de la lliçó 05-04 és l'única manera honesta de verificar que un commit fabricat amb add -p és realment complet.

Si ja has confirmat i el resultat és un desastre, el rebase interactiu de la lliçó 05-02 ho arregla, sempre que no ho hagis publicat (apartat 8).

Es converteix en:

I amb reword al primer, el resultat són dos commits nets: feat(filtres): afegeix el filtre per etiqueta i test(filtres): cobreix el filtrat per múltiples etiquetes.

Les tres ordres que resolen el 90 % dels casos:

I el flux que fa tot això automàtic, de la lliçó 05-02: git commit --fixup=<sha> mentre treballes, i git rebase -i --autosquash main al final.

Arribem al punt. La branca GT-134-timeout-sync del Bruno té quatre commits, està aprovada i entrarà a main. Hi ha tres maneres de fer-ho, i produeixen tres historials diferents.

Partim sempre d'aquesta situació:

main ha avançat amb D mentre el Bruno treballava, així que no hi ha avanç ràpid possible.

Els tres commits del Bruno entren tal qual, amb els seus SHA i les seves dates originals, i s'afegeix un commit de fusió M amb dos pares que marca on i quan es va integrar la branca. És el que vam veure a la lliçó 03-03.

Els tres commits es fonen en un de sol, S, amb un missatge nou. main queda lineal. La branca original continua existint al repositori del Bruno, però main no hi té cap referència: Git no sap que S ve de C1, C2 i C3.

Els tres commits es reescriuen damunt de D (SHA nous, mateix contingut i mateix missatge) i main avança en línia recta. És el rebase de la lliçó 05-01.

Les tres produeixen exactament el mateix arbre de fitxers. El codi final és idèntic byte a byte. L'única cosa que canvia és quina informació queda registrada sobre com s'hi va arribar. Per això la decisió no és tècnica: és una decisió sobre quina informació vols poder recuperar d'aquí a un any.

1. revert davant de bisect. Squash guanya en revert i en llegibilitat; merge i rebase guanyen en granularitat de bisect i en blame. Pregunta't què fas més sovint: desfer funcionalitats senceres, o caçar el commit exacte que va trencar alguna cosa?

2. La qualitat real dels commits del teu equip. Si les branques arriben amb wip, wip2 i ara sí, el merge i el rebase fiquen aquesta brossa a main per sempre. El squash l'absorbeix. Squash és la política que protegeix de la indisciplina; merge i rebase són les que la premien quan existeix.

3. La mida de les pull requests. Amb PRs de 200 línies, un squash perd poca informació. Amb PRs de 2.000 línies, el squash produeix commits monstruosos que arruïnen blame i bisect alhora. Squash i PRs petites van juntes; és coherent amb el que vam dir sobre la mida de la PR a la lliçó 07-02.

Cada flux del mòdul 7 té una política que li escau de manera natural:

Un matís sobre Git Flow que se sol passar per alt: en un repositori amb --no-ff sistemàtic, la lectura d'alt nivell es fa amb --first-parent (apartat 9), que amaga l'interior de cada bombolla i deixa només la seqüència d'integracions. Sense aquesta eina, un historial amb topologia és efectivament il·legible, i d'aquí ve bona part del rebuig al merge.

No hi ha una resposta universal, però sí que hi ha respostes defensables segons el projecte:

Aplicació web amb desplegament continu, equip de 3 a 15 persones → squash. És el cas de gestor-tasques. Les PRs són petites, cadascuna correspon a un tiquet GT-NNN, i el que més es fa és respondre a "què ha canviat aquesta setmana?" i "reverteix això que ha trencat producció". main queda amb una línia per canvi, revert és trivial i bisect aterra a la PR culpable, que és una granularitat suficient quan les PRs són de 200 línies. Condició innegociable: el títol del squash s'escriu amb la mateixa cura que un commit (lliçó 08-01) i s'hi propaguen els trailers rellevants, inclosos Co-authored-by i BREAKING CHANGE.

Biblioteca o producte amb versions i suport de diverses branques → merge --no-ff. Aquí cal respondre a "en quina versió va entrar això?", "aquest pedaç és a la branca 2.x?" i "de quina release va sortir?". La topologia és la resposta, i git log --first-parent, git tag --contains i git branch --contains en depenen. A més, amb cherry-pick entre branques de manteniment (lliçó 05-03), tenir els commits originals intactes facilita moltíssim la feina.

Projecte de codi obert amb molts col·laboradors externs → merge o squash, segons la qualitat de les contribucions. El projecte Git i el nucli de Linux fan servir merge amb historial de topologia, però exigeixen als contribuïdors sèries de pedaços ja netes. Un projecte que no pot exigir això fa millor de condensar.

Repositori intern petit, 1 o 2 persones → allò que us resulti còmode. Amb dues persones i context compartit, la diferència pràctica és petita. Trieu-ne un i no hi doneu més voltes.

Regla transversal, la que de debò importa:

Tria una política, configura-la a la plataforma perquè sigui l'única disponible, i escriu-la al README.md. El pitjor de tots els mons és un main on uns han condensat, altres han fusionat i altres han rebasat: no es pot llegir amb cap eina de manera consistent, --first-parent dona resultats absurds i ningú sap què esperar.

A gestor-tasques, l'acord escrit va quedar així:

Tot el de l'apartat 3 —rebase -i, fixup, reword, partir commits— té una frontera claríssima, i és la regla d'or de la lliçó 05-01:

Reescriu lliurement allò que només existeix a la teva màquina. No reescriguis mai allò que altres ja s'han baixat.

La raó, recordada en una frase: reescriure crea commits nous amb SHA diferents. Qui tingués els vells es queda amb dues versions divergents de la mateixa història, i el seu pull següent produeix un embolic que cal desfer a mà.

Hi ha un cas intermedi que cal resoldre explícitament, perquè genera discussions eternes: la teva branca de funcionalitat ja és a origin i oberta com a PR, i la vols netejar abans de fusionar.

És legítim, amb condicions:

• La branca és teva i ningú més hi ha basat feina. Si la Carla hi ha fet un commit al damunt, ja no.
• Fas servir sempre git push --force-with-lease (lliçó 04-05), mai --force a seques: si algú hi ha enviat alguna cosa mentrestant, l'operació es rebutja en lloc de destruir-la.
• Avises a la PR. Els revisors perden el fil dels seus comentaris quan els SHA canvien.
• Si ja hi ha comentaris de revisió, afegeix commits nous en lloc de reescriure, i condensa al final amb el squash de la fusió. És la raó principal per la qual el squash és tan popular: fa innecessari el rebase de neteja.
• Per revisar què ha canviat entre la versió anterior i la reescrita, git range-diff de la lliçó 07-02.

Mai, sota cap circumstància: reescriure main, una branca de release o una branca compartida. Si allà cal desfer alguna cosa, es desfà amb git revert (lliçó 05-06), que afegeix un commit nou en lloc d'esborrar el vell.

No tots els commits de fusió són iguals. N'hi ha de dues classes i convé distingir-les.

Són les deliberades: git merge --no-ff d'una branca de funcionalitat a main. El commit registra una decisió —"aquesta funcionalitat es va integrar aquí"— i el seu missatge la pot documentar:

Aquest commit és informació pura, i amb --first-parent produeix un historial d'alt nivell excel·lent.

Són les accidentals: les que apareixen en fer git pull quan el remot ha avançat.

Aquest commit no registra cap decisió. Registra que la Carla va fer pull un dimarts a les 11:40. Un main amb dos-cents d'aquests és il·legible, i omplen el graf de bombolles que no signifiquen res.

La cura és la de la lliçó 04-04, i hauria de ser a la configuració global de tothom:

O, si prefereixes que Git t'obligui a decidir en comptes de triar per tu:

Un commit de fusió té dos pares: el primer és la branca on eres (main) i el segon és la que vas fusionar. --first-parent segueix únicament el primer, amb la qual cosa amaga el contingut intern de cada branca i deixa només la seqüència d'integracions.

De centenars de línies a una desena. Aquest és l'argument que rescata el merge: un historial amb topologia no és il·legible, és un historial amb dos nivells de lectura. El d'alt nivell s'obté amb --first-parent, i el detall continua sent-hi quan el necessites.

Es mereix un àlies, reprenent els de la lliçó 06-04:

--first-parent funciona també en altres ordres:

Aquest git bisect --first-parent és especialment útil: converteix un historial amb merges en una cosa amb la mateixa granularitat que un historial de squash, però sense perdre el detall quan hi vols baixar.

L'última fila és la tensió de fons, i mereix dir-se clarament: un historial lineal és una ficció útil. Ningú va treballar en aquell ordre. L'Ana i el Bruno van programar alhora durant tres dies; l'historial lineal explica que un va acabar i després va començar l'altre. La pregunta honesta no és "què és més veritable?" sinó "em serveix de res la veritat concurrent?". Per a la majoria dels productes, no. Per a un projecte amb suport de diverses versions en paral·lel, sí, i molt.

Hi ha un tipus de commit que trenca l'historial més que cap altre, i no és un commit dolent: és necessari. El dia que l'equip de gestor-tasques va decidir adoptar Prettier, l'Ana va executar el formatador sobre tot el projecte:

El dany: a partir d'aquell moment, git blame app.js atribueix totes les línies del fitxer a l'Ana i a aquell commit. Tota la informació d'autoria i intenció dels últims dos anys queda enterrada sota un commit que no va canviar ni una coma de comportament.

Les regles perquè faci el mínim mal:

1. Aïlla el reformatatge al seu propi commit. Mai barrejat amb canvis funcionals: és l'aplicació més important del principi del commit atòmic.
2. Que aquell commit no canviï el comportament. Només el formatador; res a mà. Ha de poder reproduir-se executant l'eina.
3. Digues-ho al missatge, inclosa la versió de l'eina i la seva configuració, perquè sigui reproduïble.
4. Registra'l a .git-blame-ignore-revs.

Aquest fitxer, que vam veure a la lliçó 06-03 i que ara tanquem, és una llista de SHA que git blame ha de travessar com si no existissin:

Requisits: SHA complets de 40 caràcters (els abreujats no valen) i una línia per commit.

Es fa servir així:

Amb aquesta configuració local, git blame app.js torna a mostrar els autors reals de cada línia. Les plataformes d'allotjament més habituals reconeixen el fitxer pel seu nom convencional i l'apliquen automàticament a la seva vista de blame.

El detall que cal documentar al README.md: blame.ignoreRevsFile és configuració local (lliçó 01-05), així que no viatja amb el clon. El fitxer sí que està versionat, però cada persona l'ha d'activar. Afegeix-ho a l'script de posada en marxa del projecte:

A la lliçó 06-02 vam dir que git bisect només és útil sobre un historial "bisecable" i vam remetre aquí. Ja tenim totes les peces per definir-ho.

Un historial és bisecable quan qualsevol commit escollit a l'atzar es pot compilar, arrencar i provar.

git bisect funciona per cerca binària: et planta en un commit intermedi i et pregunta si està bé o malament. Si aquell commit ni tan sols compila, no pots respondre cap de les dues coses. L'has de marcar amb git bisect skip, i cada skip degrada la cerca. Amb prou commits trencats, la bisecció deixa de convergir i no serveix de res.

1. Commits atòmics i complets: apartat 2. Cadascun deixa el projecte funcionant.
2. El codi i les seves proves, al mateix commit.
3. CI sobre cada commit, no només sobre la punta de la branca. És l'única comprovació real. Amb la validació de la lliçó 07-06, es pot executar la compilació sobre cada commit de la PR:

4. git rebase --exec, de la lliçó 05-02, per comprovar-ho tu abans de publicar. És l'eina perfecta per a això:

Si el rebase s'atura, tens un commit no bisecable a la branca. L'arregles amb edit o fixup i continues.

Tanca el cercle de l'apartat 4:

• Squash garanteix la bisecabilitat gairebé de franc: cada commit de main és una PR sencera, que va passar el CI. La granularitat és gruixuda, però no falla mai.
• Merge amb --first-parent dona el mateix que el squash, i permet baixar al detall quan la PR és gran.
• Rebase dona la granularitat més fina, però només si cada commit compila, cosa que exigeix disciplina i una comprovació com la de dalt.

Error 1: confondre "net" amb "bonic". Un graf amb una sola línia recta que no permet revertir, bisecar ni entendre res no és net. Els cinc usos de l'apartat 1 són el criteri; l'estètica no.

Error 2: barrejar polítiques d'integració al mateix repositori. És pitjor que triar la política equivocada. Configura-la a la plataforma deixant una sola opció activa.

Error 3: condensar PRs enormes. Un squash de 2.000 línies destrueix blame i deixa bisect sense granularitat. Squash exigeix PRs petites; si no en tens, arregla això primer.

Error 4: perdre el BREAKING CHANGE al squash. És el que vam veure a l'exercici 3 de la lliçó 08-01. El quadre de missatge del squash surt preomplert amb la concatenació de tots els commits; llegeix-lo i edita'l, no l'acceptis tal qual ni el buidis.

Error 5: rebasar una branca compartida. La regla d'or de la 05-01 no té excepcions pràctiques. Si dubtes de si algú més la té, no la rebasis.

Error 6: acumular fusions de pull. git config --global pull.rebase true i desapareixen. És un canvi d'una línia que millora l'historial per a tota la vida.

Error 7: fer el reformatatge massiu barrejat amb un canvi funcional. Enterraràs el canvi funcional en 900 línies de soroll i arruïnaràs el blame sense possibilitat de rescat, perquè .git-blame-ignore-revs no pot ignorar un commit que a més conté codi real.

Error 8: pensar que --first-parent no existeix. Molta gent rebutja el merge per "il·legible" sense haver provat mai git log --first-parent. Prova-ho abans de decidir.

Consell 1: escriu la política al README.md. Amb les condicions (mida de PR, format del títol, trailers). El Diego, que ve de fora, la necessita abans de la seva primera PR.

Consell 2: git rebase main --exec "npm test" abans d'obrir la PR. És la manera més barata de garantir que la teva branca és bisecable.

Consell 3: àlies per llegir. git config --global alias.integracions "log --oneline --first-parent --decorate".

Consell 4: revisa la teva branca abans de publicar-la. git log --oneline main..HEAD. Si hi veus un wip, encara et queda feina.

Consell 5: .git-blame-ignore-revs des del primer commit. Crea'l buit, amb la capçalera comentada. Així, el dia del primer reformatatge massiu, el lloc ja existeix.

Consell 6: esborra les branques fusionades. Amb squash, la branca no queda enllaçada des de main; deixar-la viva suggereix que hi ha feina pendent. Recorda git branch --merged i git fetch --prune de la lliçó 03-06.

Munta un repositori de proves que reprodueixi la situació de l'apartat 4: main amb dos commits, una branca amb tres commits i un commit posterior a main. Després, des de tres còpies del mateix estat, integra la branca amb cadascuna de les tres polítiques.

Per a cada resultat, respon:

1. Quants commits té main?
2. Què mostra git log --oneline --graph?
3. Què mostra git log --oneline --first-parent?
4. Quina ordre exacta faries servir per desfer la integració completa?
5. Si bisect assenyalés el problema, a quin nivell de detall et deixaria?

Simula el commit patològic de l'apartat 2:

1. Crea un app.js amb tres funcions i confirma'l.
2. En un sol canvi, modifica una funció (canvi funcional), torna a sagnar-ne una altra (reformatatge) i corregeix una errada en un comentari de la tercera.
3. Fes servir git add -p (amb s i e quan calgui) per separar els tres en tres commits atòmics amb missatges en Conventional Commits.
4. Verifica amb git stash push --keep-index que el primer commit funciona per si sol.
5. Comprova amb git log --oneline --stat que cada commit toca només el que li pertoca.

1. Crea un repositori amb un estils.css d'unes 20 línies, escrit en tres commits de tres autors diferents (fes servir git -c user.name=... -c user.email=... commit).
2. Comprova amb git blame estils.css que l'autoria és correcta.
3. Aplica un reformatatge massiu (per exemple, canvia tot el sagnat) i confirma'l com a style: torna a sagnar estils.css a 2 espais.
4. Comprova el dany amb git blame.
5. Crea .git-blame-ignore-revs, configura blame.ignoreRevsFile i demostra que l'autoria original es recupera.
6. Explica per què el pas 5 hauria estat impossible si el reformatatge hagués vingut barrejat amb un canvi funcional.

Solució 1:

Les respostes:

Observa la fila 4: amb rebase, desfer la integració exigeix revertir tres commits en ordre invers, i si l'intermedi depèn del primer, hi ha conflictes. És el desavantatge més pràctic del rebase pur.

Solució 2:

Si els canvis fossin al mateix fragment, s el parteix i e permet editar el fragment a mà, deixant amb - les línies que no vols preparar.

A la pràctica es fa abans de confirmar: prepares el fragment, git stash push --keep-index aparta tota la resta, executes les proves sobre exactament el que entrarà, i només llavors confirmes i fas git stash pop.

Solució 3:

Ara totes les línies sagnades apareixen a nom de l'Ana i del commit d'estil.

6. Perquè .git-blame-ignore-revs funciona saltant-se el commit sencer: quan blame troba aquell SHA, atribueix la línia al commit anterior que la va tocar. Si el commit contingués a més un canvi funcional real, ignorar-lo atribuiria també aquell canvi funcional a qui no el va fer, i perdries la informació de qui va introduir el codi de debò. El fitxer només és segur amb commits que demostrablement no canvien el comportament. Per això la regla 1 de l'apartat 11 —aïllar el reformatatge— no és un consell estètic: és la condició que fa possible el rescat.

L'essencial d'aquesta lliçó:

• Un historial és net quan qualsevol commit es pot entendre, provar, revertir i atribuir per separat. Els cinc usos reals —blame, bisect, revert, revisió i auditoria— són el criteri; l'estètica del graf no ho és.
• El commit atòmic —un canvi complet i només un— és la unitat que fa possible tota la resta. No es programa així: es fabrica després, amb git add -p abans de confirmar i amb git rebase -i després.
• La decisió que vam deixar oberta a la 07-04 queda tancada així:
  • Merge --no-ff quan la topologia és informació: Git Flow, biblioteques amb diverses versions vives, projectes amb branques de manteniment. Es llegeix amb --first-parent.
  • Squash quan el que importa és que main sigui una llista llegible de canvis desplegables: GitHub Flow, aplicacions web, equips les branques dels quals arriben amb wip. Exigeix PRs petites i un títol de squash escrit amb cura.
  • Rebase quan vols granularitat fina i linealitat alhora, i l'equip té la disciplina perquè cada commit compili: Trunk Based Development.
  • I per damunt de les tres: tria'n una, configura-la com a única opció a la plataforma i escriu-la al README.md. Barrejar-les és pitjor que triar malament.
• Es neteja abans de publicar; no es toca el que s'ha publicat. La regla d'or de la 05-01 es manté, amb l'única zona grisa de la teva pròpia branca de PR, i sempre amb --force-with-lease i avís previ.
• Els commits de fusió deliberats són informació; els accidentals de git pull són soroll que s'elimina amb pull.rebase true. I --first-parent converteix un historial amb topologia en un historial de dos nivells de lectura, cosa que rescata el merge de l'acusació d'il·legible.
• Un reformatatge massiu s'aïlla al seu propi commit, es documenta i es registra a .git-blame-ignore-revs amb el SHA complet, activant-lo amb blame.ignoreRevsFile. Aïllar-lo no és estètica: és el que fa possible el rescat.
• Un historial és bisecable quan qualsevol commit compila i es pot provar. Es garanteix amb commits atòmics, amb el codi i les seves proves junts, amb git rebase --exec abans de publicar i amb CI sobre cada commit.

gestor-tasques ja té missatges que expliquen el perquè i un historial que es pot llegir, bisecar i revertir. Però continua tenint a dins coses que no hi haurien de ser: la carpeta node_modules que el Bruno va pujar sense adonar-se'n, els .DS_Store de macOS, els Thumbs.db de Windows i un fitxer de configuració amb una contrasenya.

El següent és decidir què no entra mai en un repositori, a la lliçó 08-03: Ignorant Fitxers amb .gitignore.