Tancàvem el mòdul 4 amb un advertiment: a partir d'ara l'historial és compartit. L'Ana, en Bruno i la Carla treballen sobre el mateix repositori de git.exemple.cat, i cada push hi deixa commits que les altres dues persones poden baixar-se en qualsevol moment. Aquesta és exactament la circumstància que converteix git rebase en l'eina més útil i més temuda de Git.

git rebase serveix per a una cosa molt concreta: agafar una sèrie de commits i tornar-los a aplicar sobre una altra base. Serveix perquè una branca que va néixer fa tres dies torni a estar «al damunt» de main sense embrutar l'historial amb fusions; serveix per reordenar i netejar la teva feina abans d'ensenyar-la a ningú; i serveix per moure una branca que penjava del lloc equivocat. El que fa por d'ella és l'altra cara: no mou commits, els substitueix per uns de nous. I substituir commits que ja estan publicats és, com veurem, una manera força eficaç d'arruïnar la tarda als teus companys.

Aquesta lliçó explica el mecanisme amb prou detall perquè no hi hagi màgia: quins objectes es creen, quins hashos canvien, què es conserva, com es resolen els conflictes que apareixen a mitges i —sobretot— quan convé fer servir rebase i quan convé fer servir merge.

1. La regla d'or del mòdul
2. Què fa git rebase realment
3. Un rebase pas a pas a gestor-tasques
4. Què es conserva i què canvia als commits reaplicats
5. Rebase davant de merge
6. git rebase --onto: moure un tram concret
7. Conflictes durant un rebase: --continue, --skip, --abort
8. La inversió d'ours i theirs
9. Trencar la regla d'or: què passa exactament
10. git pull --rebase
11. rebase.autoStash i altres opcions còmodes
12. La xarxa de seguretat

Abans d'escriure ni una sola ordre, la regla que governa tot el mòdul 5:

No reescriguis historial que ja has publicat i que altres persones poden tenir descarregat.

Tot el que veurem a les lliçons 05-01, 05-02 i 05-03 crea commits nous que en substitueixen d'altres. Mentre aquests commits visquin només al teu disc, reescriure'ls és gratis: ningú més no els ha vist. Tan bon punt els envies a git.exemple.cat, deixen de ser teus: passen a formar part d'una realitat compartida, i canviar-los obliga els altres a refer la seva còpia.

La regla té una excepció molt acotada i molt coneguda: la teva pròpia branca de treball, publicada només per tenir-ne còpia o per a una revisió, que ningú més no fa servir com a base. És un cas legítim i habitual, però exigeix avisar i exigeix --force-with-lease (lliçó 04-05). Tornarem a la regla a cada apartat que reescrigui commits, fins que resulti carregós. Aquest és l'objectiu.

La frase que se sol repetir és «el rebase mou els teus commits al damunt d'una altra branca». És còmoda i és falsa, i la diferència importa.

Recorda el model de dades de la lliçó 01-04: un commit és un objecte immutable el hash SHA-1 del qual es calcula a partir de tot el seu contingut, i aquest contingut inclou el hash del seu pare. Per tant:

• Si canvies el pare d'un commit, canvia el seu contingut.
• Si canvia el seu contingut, canvia el seu hash.
• Si canvia el seu hash, ja no és el mateix commit: és un altre objecte diferent.

Un commit no es pot «moure» igual que no es pot canviar el passat. El que fa git rebase és:

1. Calcular la llista de commits que són a la teva branca i no a la nova base.
2. Desar el canvi (el diff) que introdueix cadascun.
3. Situar-se a la nova base.
4. Aplicar aquests canvis un a un, creant un commit nou per cadascun.
5. Moure la referència de branca a la punta de la cadena nova.

Els commits antics continuen existint a la base de dades d'objectes —els objectes de Git no s'esborren a l'instant—, però es queden sense cap branca que els assoleixi. Són, a efectes pràctics, història morta.

Aquest és el punt de partida: la Carla va crear la seva branca quan main era a b3f7c21, i mentre treballava l'Ana va publicar e91d4a8. Després del rebase:

Fixa't bé en els identificadors: 7c2e5f9 i a4b1d83 han desaparegut del dibuix, i al seu lloc hi ha d5e8f31 i 92c7a06. El contingut dels canvis és el mateix, els missatges són els mateixos, l'autor és el mateix. Els commits, no.

La Carla porta dos dies amb funcionalitat/etiquetes-color: vol que cada tasca pugui portar un color. Mentrestant, l'Ana ha publicat un canvi a main. La Carla vol posar-se al dia sense crear un commit de fusió.

La bifurcació és clara: dos commits per una banda, un per l'altra, i b3f7c21 com a ancestre comú. Comprovem quins commits es reaplicaran abans de tocar res:

Aquesta és exactament la llista de què parlàvem: el rang main..HEAD que vas aprendre a la lliçó 02-06. Ara sí:

Ja no hi ha bifurcació: una sola línia recta. I els hashos dels dos commits de la Carla han canviat. Val la pena verificar amb git show que el canvi és idèntic:

Mateix autor, mateixa data d'autoria, mateix missatge, mateix diff. Objecte diferent.

Un detall important per al final: com que la branca de la Carla no estava publicada, aquí no hi ha res a negociar. Si ho estigués, el següent git push seria rebutjat per non-fast-forward (lliçó 04-05) i caldria fer servir --force-with-lease.

Aquesta taula resol la majoria dels dubtes de qui comença:

Dues conseqüències pràctiques:

• git log mostra per defecte la data d'autoria, així que després d'un rebase l'historial continua ensenyant les dates originals. Si vols veure la de confirmació: git log --pretty=fuller.
• Si al teu equip algú mira «qui va confirmar què», el rebase et posa a tu com a committer de commits aliens. No és cap problema, però convé saber-ho.

Totes dues integren la feina d'una branca amb la d'una altra. La diferència no és tècnica sinó narrativa: quina història vols que expliqui el repositori.

I el criteri, resumit en tres regles que sí que pots memoritzar:

1. Rebase per al que encara és teu. La teva branca local, abans de publicar-la o abans de demanar-ne la integració: posa-la al dia sobre main amb rebase.
2. Merge per ajuntar històries que ja són públiques. Integrar una branca de funcionalitat acabada a main és un fet que mereix quedar registrat; allà un merge (sovint --no-ff, lliçó 03-03) és l'opció honesta.
3. Davant del dubte, merge. És l'opció que mai no destrueix res.

Hi ha equips que porten això a l'extrem en un sentit («historial lineal sempre») i d'altres en el contrari («no reescriure mai res»). Totes dues postures són defensables i les veurem amb nom propi al mòdul 7 (fluxos de treball) i a la lliçó 08-02, quan parlem de la política d'historial net. Aquí ens ocupa el mecanisme.

git rebase <base> cobreix el 90 % dels casos, però té un supòsit implícit: que vols reaplicar tot el que hi ha entre l'ancestre comú i la teva branca. De vegades no és això el que vols.

Li va passar a la Carla. Va començar funcionalitat/ordre-per-data sense adonar-se que estava situada a funcionalitat/etiquetes-color en lloc de a main. Ara la seva branca nova arrossega els dos commits de les etiquetes de color, que no hi tenen res a veure.

Vol que funcionalitat/ordre-per-data pengi directament de main (que és a e91d4a8) i contingui només 3f9a2c4 i 6b1e7d5. Per a això existeix la forma de tres arguments:

La manera de llegir-la en veu alta és aquesta:

• <fins-a> — la branca que vull moure (si l'omets, la branca actual).
• <des-de> — el punt a partir del qual comencen els commits que vull endur-me. Aquest commit no s'inclou; funciona com el límit exclusiu d'un rang des-de..fins-a.
• <nova-base> — on vull que quedin enganxats.

Aplicat al cas de la Carla:

Els dos commits de la data s'han reaplicat sobre main amb hashos nous, i la branca de les etiquetes de color s'ha quedat on era, intacta.

Altres usos habituals de --onto, perquè reconeguis el patró:

Aquest últim és un bon exercici mental: 8b6d3c2 és el commit que volem eliminar, 4e7f2a9 és el seu pare, i estem dient «agafa tot el que hi ha després de 8b6d3c2 i enganxa-ho directament sobre el seu pare». El rebase interactiu (lliçó 05-02) té una manera molt més còmoda de fer el mateix, però convé entendre que per sota és això.

Un rebase aplica commits un a un, així que es pot aturar un cop per cada commit. La mecànica de resolució —els marcadors <<<<<<<, git status, editar, git add— és exactament la que vas aprendre a la lliçó 03-05; no la repetim. El que canvia és com se surt de l'embús.

Suposem que la Carla rebasa i el segon commit xoca:

Aquest bloc de git status és el teu quadre de comandaments: et diu en quin commit de la llista vas i què queda. Les tres sortides:

Tres advertiments importants:

• --skip no vol dir «salta't el conflicte»: vol dir «llença aquest commit a les escombraries». Si el commit tenia canvis que no són enlloc més, els perds de la branca resultant. Fes-lo servir només quan estiguis segur que el seu contingut ja està aplicat.
• --abort és completament segur. Retorna la branca exactament on era, amb els commits originals i els seus hashos originals. Quan dubtis, avorta i pensa amb el repositori en calma.
• No facis git commit a mà durant un rebase. Després de resoldre i fer git add, és git rebase --continue qui crea el commit. Si fas git commit, --continue et dirà que no queda res per confirmar (i en versions antigues pot deixar la llista descompensada).

Un detall útil: si després de resoldre el conflicte el resultat és idèntic a la base (és a dir, el teu commit ja no aporta res), git rebase --continue ho detecta i et proposa saltar-lo. És normal i no indica cap problema.

Aquí hi ha el parany que confon tothom, veterans inclosos.

En una fusió normal (lliçó 03-05), ours és la teva branca —on ets— i theirs és la branca que portes. Intuïtiu.

En un rebase s'inverteix. I no és cap caprici: és la conseqüència lògica del mecanisme. Recorda que un rebase primer es col·loca a la nova base i després aplica els teus commits al damunt, un a un, com si fossin pedaços aliens. Per tant, a cada pas:

Dit d'una manera memorable: durant un rebase, «els seus» ets tu.

La conseqüència pràctica és directa. Si durant un rebase vols quedar-te amb la teva versió del fitxer:

El mateix val per a -X ours / -X theirs quan els passes al rebase, i per als noms de les etapes de l'índex (:2: i :3:) que vas veure a 03-05. Si mai dubtes, no ho endevinis: mira el contingut abans de decidir.

Un consell que estalvia molts disgustos: configura l'estil zdiff3 (lliçó 03-05) també aquí. Veure l'ancestre comú dins del marcador fa l'orientació molt menys dependent de recordar qui és qui:

I si el mateix conflicte es repeteix commit rere commit dins del mateix rebase, existeix git rerere (reuse recorded resolution), que memoritza com vas resoldre un conflicte i l'aplica sol la propera vegada que aparegui idèntic. Es va esmentar a 03-05 i la seva configuració se surt d'aquesta lliçó.

Vegem-ho amb noms i cognoms, perquè el mecanisme del desastre explica la regla millor que qualsevol advertiment.

1. En Bruno publica funcionalitat/exportacio-csv amb tres commits: 2a7f4c1, 9e3b8d6, 5c1a9f2.
2. La Carla fa git fetch i crea la seva branca a partir d'aquella feina. Ara té aquests tres commits al seu disc.
3. En Bruno rebasa la seva branca sobre main perquè main ha avançat. Els seus tres commits es converteixen en d8b2e50, 71f6c34, ae95d18.
4. En Bruno fa git push --force-with-lease. El servidor ara apunta a ae95d18.
5. La Carla fa git pull.

El que veu la Carla:

I a partir d'aquí, segons la seva configuració de pull:

• Amb pull.ff only (la que vam configurar a 01-06): el pull falla amb un avís de divergència. És el millor dels casos: la Carla se n'assabenta i pot preguntar.
• Amb merge: Git fusiona la cadena vella amb la nova i apareixen els tres commits duplicats, cadascun dues vegades amb hashos diferents, més un commit de fusió, més un grapat de conflictes absurds on cada canvi xoca amb si mateix.
• Amb rebase: la Carla reaplica els seus commits (que inclouen els tres vells d'en Bruno) sobre la cadena nova, i obté el mateix festival de duplicats.

I si la Carla resol malament i publica, els commits vells tornen al servidor i el rebase d'en Bruno queda desfet. És el cicle clàssic: algú rebasa, algú ho reverteix sense voler, i l'historial acaba amb tot duplicat.

Com s'evita, en ordre d'eficàcia:

1. No reescriure branques compartides. Si més d'una persona hi treballa, s'integra amb merge i punt.
2. Si la branca és teva i publicada només com a còpia, rebasa quan vulguis, però avisa abans de forçar i fes servir sempre --force-with-lease (mai --force), que es nega si algú ha publicat alguna cosa que tu no tens.
3. Si has estat la víctima, la sortida és git reset --hard origin/<branca> per descartar la teva còpia vella i tornar a aplicar el teu al damunt. La casuística completa, amb els passos per no perdre feina, és a la lliçó 09-03.

A la lliçó 04-04 vam deixar pendent aquesta opció. Ja la podem entendre del tot.

git pull és fetch + integració. Amb --rebase, la integració és un rebase dels teus commits locals sobre el que acabes de portar:

Comparació dels tres modes, ara completa:

Per què agrada tant: quan dues persones toquen coses diferents del mateix projecte i sincronitzen sovint, pull amb merge genera un reguitzell de commits «Merge branch 'main' of git.exemple.cat…» que no expliquen absolutament res. pull --rebase els elimina.

I per què cal fer-lo servir amb cap: reescriu els teus commits locals. Això és inofensiu si no els has publicat (que és el cas típic: acabes de fer-los i encara no hi ha hagut push), i és exactament l'escenari de l'apartat 9 si sí que els has publicat.

Per deixar-ho configurat:

pull.rebase merges (equivalent a --rebase-merges) mereix una nota: per defecte, un rebase descarta els commits de fusió de la cadena que reaplica i ho aplana tot en una línia. Si tenies fusions intencionades a la teva feina local, merges les conserva reconstruint-les.

Si deixes pull.ff only com a configuració global (la nostra recomanació de 01-06 i la més segura per aprendre), sempre pots demanar el rebase puntualment amb git pull --rebase. L'explícit guanya.

git rebase exigeix un directori de treball net: si tens canvis sense confirmar, es nega a començar.

La solució manual és git stash, rebasar i git stash pop (lliçó 05-04). L'automàtica:

Amb això, Git aparta els canvis sol, rebasa i els retorna en acabar. Si en retornar-los hi ha conflicte, t'avisa i el desament temporal es queda estalvi a la pila. És una comoditat excel·lent, i el seu equivalent per a pull és rebase.autoStash combinat amb pull.rebase, o git pull --rebase --autostash.

Altres opcions que convé conèixer:

rebase.updateRefs resol un problema molest: si tens branques apilades (b surt d'a, c surt de b) i rebases c, les referències intermèdies es quedaven apuntant als commits vells. Amb aquesta opció activada, Git les arrossega.

Un rebase pot sortir malament: pots fer --skip d'un commit que no tocava, resoldre un conflicte al revés, o adonar-te als deu minuts que la base era una altra.

Bona notícia: els commits originals continuen allà. Com vam veure a l'apartat 2, el rebase no esborra objectes, només deixa de referenciar-los, i Git guarda un registre de per on ha passat cada referència. Aquest registre és el reflog, i amb ell es recupera l'estat anterior a un rebase gairebé sempre.

Aquest curs dedica la lliçó 09-04: Recuperant Confirmacions Perdudes a aquest tema, inclòs el procediment exacte per desfer un rebase desastrós. Aquí n'hi ha prou que sàpigues dues coses:

1. Que la xarxa existeix: un rebase mal fet és recuperable durant setmanes.
2. Que no és excusa per saltar-se la regla d'or, perquè el reflog és local. Recupera el teu repositori; no arregla els dels teus companys que ja es van descarregar els commits que vas reescriure.

I el reflex barat que sí que pots adoptar avui: abans d'un rebase que t'imposi respecte, deixa una marca.

Una branca són 41 bytes. La tranquil·litat, bastant més.

Error 1: creure que el rebase «mou» els commits. Els substitueix per uns de nous amb hashos diferents. Tot el perill del rebase deriva d'aquest fet, i qui l'interioritza deixa de tenir sorpreses.

Error 2: rebasar una branca compartida. Si en Bruno i la Carla treballen tots dos a funcionalitat/exportacio-csv, cap dels dos no la rebasa. S'integra amb merge. La comoditat d'un historial lineal no compensa una tarda de duplicats.

Error 3: fer servir --ours durant un rebase pensant que és la teva versió. És la de la base. Durant un rebase, tu ets theirs. Davant del dubte, git show :2:fitxer i git show :3:fitxer.

Error 4: fer servir git rebase --skip per «treure'm el conflicte de sobre». Descarta el commit sencer. Si contenia feina real, desapareix de la branca resultant.

Error 5: fer git commit enmig d'un rebase. Qui confirma és git rebase --continue. Tu només resols i fas git add.

Error 6: git push --force en lloc de --force-with-lease. El primer trepitja el que hi hagi al servidor sense mirar; el segon es nega si algú ha publicat alguna cosa que tu no tens. La diferència es va explicar a 04-05 i aquí és on de debò importa.

Error 7: rebasar sense fetch previ. git rebase main fa servir el teu main local, que pot portar dos dies desactualitzat. L'ordre correcte és git fetch origin, actualitzar main, i llavors rebasar (o rebasar directament sobre origin/main).

Consell 1: rebasa aviat i sovint. Una branca que es posa al dia cada dia té conflictes petits; una que ho fa al cap de dues setmanes té un conflicte per commit i tots grossos.

Consell 2: mira sempre git log --oneline main..HEAD abans de rebasar. Aquesta llista és exactament el que es reescriurà. Si et sorprèn la seva llargada o el seu contingut, la base que anaves a fer servir no era la que et pensaves.

Consell 3: activa rebase.autoStash i merge.conflictStyle zdiff3. Dues línies de configuració que eliminen dues de les friccions més habituals.

Consell 4: si el rebase es posa lleig, avorta. git rebase --abort és gratis i sempre funciona. Tornar-ho a provar amb el cap fred, amb els commits més petits o amb --onto ben triat sol ser molt més ràpid que insistir.

Crea un repositori de pràctiques amb una branca main i una branca funcionalitat/alguna-cosa que en surti. Afegeix dos commits a cadascuna. Després:

1. Anota els hashos dels dos commits de la branca de funcionalitat.
2. Rebasa-la sobre main.
3. Demostra amb ordres que els hashos han canviat, que la data d'autoria s'ha conservat i que la de confirmació no.
4. Demostra que els commits originals continuen existint a la base de dades d'objectes.

Reprodueix el problema de la Carla: crea branca-a sobre main amb dos commits, i branca-b sobre branca-a amb dos més. Després, fent servir git rebase --onto, aconsegueix que branca-b pengi de main contenint només els seus dos commits propis. Verifica el resultat amb git log --graph --all --oneline.

Provoca un conflicte durant un rebase (les dues branques modificant la mateixa línia d'un fitxer). Amb el rebase aturat:

1. Mostra les tres versions del fitxer des de l'índex (etapes :1:, :2: i :3:) i identifica quina correspon al teu commit.
2. Resol quedant-te amb la teva versió fent servir l'opció correcta de git checkout.
3. Acaba el rebase.
4. Repeteix l'experiment des de zero però avortant amb --abort, i comprova que la branca torna a tenir els seus hashos originals.

Solució 1:

El hash és diferent, la data d'autoria idèntica i la de confirmació és la del moment del rebase.

Existeix com a objecte encara que cap branca no l'assoleixi. És el que fa possible la recuperació de la lliçó 09-04.

Solució 2:

branca-b penja de main amb els seus dos commits i sense rastre d'A1 ni d'A2.

Solució 3:

L'etapa :3: és la meva: durant un rebase, el meu commit és theirs.

--abort restaura la branca exactament com era: mateixos commits, mateixos hashos, mateix directori de treball.

git rebase deixa de fer por tan bon punt s'entén què fa de debò. L'essencial d'aquesta lliçó:

• El rebase no mou commits: crea commits nous. Canvia el pare, després canvia el hash, després és un altre objecte. Els originals queden orfes però continuen a la base de dades.
• git rebase <base> reaplica sobre <base> tot el que hi ha a la teva branca i no hi és; git rebase --onto <nova-base> <des-de> <fins-a> et deixa triar amb precisió quin tram moure i cap on.
• Rebase davant de merge no és una qüestió tècnica sinó narrativa: el merge explica el que va passar, el rebase explica una versió ordenada. Rebase per al que encara és teu; merge per ajuntar històries públiques; davant del dubte, merge.
• Els conflictes d'un rebase es resolen igual que els d'una fusió (lliçó 03-05), però se'n surt amb --continue, --skip (que descarta el commit) o --abort (que és sempre segur), i les bandes ours/theirs estan invertides: la base és ours, el teu commit és theirs.
• La regla d'or: no reescriguis historial publicat que altres puguin tenir. Si ho fas, els teus companys acaben amb tot duplicat i l'única sortida és coordinar-se.
• git pull --rebase aplica aquesta mateixa idea en sincronitzar i elimina els commits de fusió inútils; rebase.autoStash treu la fricció de tenir canvis sense confirmar.
• El reflog és la xarxa de seguretat per al teu repositori (lliçó 09-04), no per al dels altres.

Fins ara hem fet servir el rebase per a una sola cosa: canviar la base. Però el mateix mecanisme —descompondre una branca en una llista de commits i tornar-los a aplicar— permet molt més si et deixen editar aquesta llista abans que s'executi: canviar l'ordre, unir dos commits en un, partir-ne un en dos, corregir un missatge o eliminar un commit del tot.

Això és exactament el que fa git rebase -i, i és el que en Bruno necessita per convertir els seus commits apany, wip 2 i wip 3 en alguna cosa que es pugui ensenyar sense vergonya. Ho veiem a la lliçó 05-02: Rebase Interactiu.