La lliçó anterior va resoldre quins fitxers no han d'entrar al repositori. Aquesta tracta del problema complementari i menys conegut: els fitxers que sí que hi entren, però que Git no hauria de tractar tots igual.

I comença amb un problema molt concret que la Carla arrossega des del mòdul 1. Cada vegada que obre estils.css al seu editor de Windows 11, hi fa un canvi d'una línia i executa git diff, apareix això:

243 línies modificades per haver-ne canviat una. El fitxer sencer. I quan ho confirma, l'Ana i el Bruno reben una PR irrevisable, el git blame queda arruïnat (lliçó 06-03) i cada fusió genera conflictes que no signifiquen res. El culpable són els finals de línia, i la solució definitiva és .gitattributes.

Aquest fitxer és l'eina menys coneguda i més útil del repertori de Git. Permet dir-li a Git com ha de tractar cada tipus de fitxer: com normalitzar-lo en desar-lo, si és text o binari, com mostrar-ne les diferències, com fusionar-lo i si s'ha d'incloure en exportar.

1. Què és .gitattributes i en què es diferencia de .gitignore
2. Sintaxi i precedència
3. El problema dels finals de línia
4. text, eol i text=auto
5. .gitattributes davant de core.autocrlf
6. Renormalitzar un projecte que ja té el problema
7. Marcar binaris amb -text i binary
8. Diffs personalitzats: diff=<driver>
9. Que @@ mostri el nom de la funció
10. textconv: veure el text de fitxers binaris
11. Drivers de fusió i el cas merge=union
12. export-ignore i git archive
13. Altres atributs: filter, linguist-*, export-subst
14. Taula resum

Els dos fitxers s'assemblen —viuen al repositori, fan servir patrons de fitxer, es versionen— i fan coses completament diferents:

La forma d'una línia de .gitattributes és sempre la mateixa:

Els quatre estats possibles d'un atribut:

Els patrons són els mateixos que a .gitignore (lliçó 08-03): *, ?, **, la barra inicial que ancora a l'arrel, la barra final que restringeix a directoris. Tot el que hi vas aprendre val aquí.

Les diferències són en on es busca i en qui guanya:

Precedència, de menor a major: sistema → global → .git/info/attributes → .gitattributes de l'arrel → .gitattributes de subdirectoris més profunds. I dins d'un mateix fitxer, guanya l'última línia que coincideix, igual que a .gitignore.

La fila que importa és la primera: .gitattributes es versiona i viatja amb el repositori. Aquesta propietat, que sembla un detall administratiu, és exactament el que resol el problema de la Carla, com veurem a l'apartat 5.

Per consultar quins atributs s'apliquen realment a un fitxer:

git check-attr és a .gitattributes el que git check-ignore -v és a .gitignore: l'eina de diagnòstic. Fes-la servir sempre que alguna cosa no es comporti com esperaves.

Per resoldre el problema de la Carla cal entendre'n l'origen, que és històric i ridícul.

Un salt de línia es codifica de dues maneres diferents segons el sistema:

Ve de les màquines d'escriure: el retorn de carro tornava el capçal al principi i l'avanç de línia feia baixar el paper. Unix va decidir que amb un caràcter n'hi havia prou; DOS va mantenir-ne els dos. Cinquanta anys després encara ho paguem.

Per a Git, \n i \r\n són bytes diferents, o sigui que una línia que només difereix en el final de línia és una línia diferent. D'aquí ve el 243 insercions, 243 supressions de la Carla: el seu editor va desar el fitxer sencer amb CRLF, i les 243 línies van canviar de debò, encara que visualment no en canviés cap.

Els símptomes típics, tots amb la mateixa causa:

• git diff mostra el fitxer sencer modificat sense cap canvi visible.
• git status marca com a modificats fitxers que no has tocat.
• Conflictes de fusió a cada línia d'un fitxer que només va tocar una persona.
• git blame ho atribueix tot a l'últim que va desar des d'un altre sistema.
• Un script de shell versionat des de Windows falla a Linux amb bad interpreter: /bin/bash^M.

La solució conceptual és una convenció que Git implementa de manera nativa:

Al repositori, tot es desa amb LF. A la còpia de treball, cadascú té el que el seu sistema necessita.

La conversió es fa en confirmar (normalització) i en extreure (desnormalització), i la controla l'atribut text.

Els dos matisos importants:

• eol=lf no vol dir "desa LF al repositori": al repositori sempre hi ha LF quan el fitxer és text. eol controla què s'escriu al teu disc en extreure.
• text=auto decideix per heurística: Git examina els primers 8.000 bytes i, si hi troba un byte nul, el considera binari. És una bona heurística, però no infal·lible (apartat 7).

Aquest és el punt de partida que serveix per a gairebé qualsevol projecte:

I aquesta és la versió explícita, que és la que de debò convé, perquè no depèn de cap heurística:

Les dues seccions del mig són les que eviten errors reals:

• *.sh text eol=lf: un script de shell amb CRLF no arrenca a Linux. L'intèrpret busca /bin/bash i troba /bin/bash\r. Amb aquesta regla, encara que la Carla l'editi a Windows, al seu disc hi tindrà LF i funcionarà dins del contenidor.
• *.bat text eol=crlf: els .bat antics de Windows necessiten CRLF. Encara que l'Ana els editi a Ubuntu, al disc de la Carla hi arribaran amb CRLF.

A la lliçó 01-06 vam veure core.autocrlf, que resol el mateix problema des de l'altre costat. És el moment de comparar els dos enfocaments i explicar per què en guanya un.

core.autocrlf és configuració de màquina (lliçó 01-05), amb tres valors:

Funciona, i si tothom ho té ben configurat el problema desapareix. El problema és "si tothom ho té ben configurat".

L'última fila és la clau tècnica: quan un fitxer té l'atribut text definit, core.autocrlf s'ignora completament per a aquell fitxer. Els atributs guanyen.

I les dues files anteriors són les pràctiques. Quan el Diego, el col·laborador extern, clona el seu fork de gestor-tasques, ningú li pot demanar que configuri el seu core.autocrlf abans de tocar res. Amb .gitattributes no cal: la política viatja dins del repositori i se li aplica tota sola.

La regla: .gitattributes per a la política del projecte; core.autocrlf com a xarxa de seguretat personal en repositoris que no en tinguin. Si tens .gitattributes, core.autocrlf sobra.

Hi ha, a més, un ajust útil que detecta el problema abans que entri:

Afegir el .gitattributes no arregla el passat. Els fitxers ja confirmats amb CRLF continuen amb CRLF dins del repositori, i fins que algú no els toqui el problema persisteix. Cal renormalitzar, i Git té una ordre exactament per a això.

Reescriu el contingut de cada fitxer seguit a l'índex aplicant els filtres del .gitattributes a la versió que hi ha al repositori, sense tocar la teva còpia de treball. És la manera segura de dir "aplica la política nova a tot el que ja és a dins".

El que en resulta és exactament el cas de l'apartat 11 de la lliçó 08-02: un commit gegantí que no canvia ni una coma de comportament i que arruïna el git blame. Així que se li aplica el mateix tractament:

Renormalitzar toca tots els fitxers, o sigui que qualsevol branca oberta en aquell moment entrarà en conflicte massiu en fusionar-se. La seqüència sensata:

1. Avisa amb antelació i fixa una hora.
2. Que tothom fusioni o tanqui les seves branques abans d'aquella hora.
3. Una persona fa la renormalització en una PR pròpia, sense res més a dins.
4. Es fusiona tan bon punt està aprovada, sense deixar-la oberta dies.
5. Tothom fa pull i, si tenia branques vives, les rebasa sobre el commit de renormalització.
6. Si algú té conflictes només de finals de línia, es resolen en bloc:

Una comprovació prèvia molt útil, per veure quant mal hi ha abans de començar:

Es llegeix així: i/ és el final de línia a l'índex (el repositori) i w/ el de la teva còpia de treball. La línia d'index.html amb i/crlf és la que revela el problema: hi ha CRLF dins del repositori, que és el que cal renormalitzar.

Un fitxer binari no s'ha de convertir mai. Si Git aplica la conversió de finals de línia a un PNG, el corromp: qualsevol byte 0x0D 0x0A dins de les dades de la imatge es converteix en 0x0A i el fitxer deixa de ser vàlid.

text=auto detecta la majoria dels binaris amb l'heurística del byte nul, però falla en casos reals: fitxers comprimits sense bytes nuls als primers 8 KB, formats de dades mixtos, fitxers de font amb capçalera de text. Declarar-los explícitament surt més barat que descobrir el problema.

binary és un macroatribut: equival exactament a escriure

És a dir, tres coses alhora:

L'efecte de -merge mereix una explicació, perquè canvia el que veus en un conflicte. Sense ell, Git intentaria barrejar dues versions d'un PNG i produiria un fitxer corrupte amb marcadors <<<<<<< a dins. Amb ell, el conflicte es planteja com una tria entre les dues versions senceres:

I es resol triant-ne una de les dues, com vam veure a la lliçó 03-05:

Quan el fitxer no és text normalitzable però sí que vols poder veure'l en un diff. El cas típic és un SVG gran o un fitxer de dades amb codificació fixa:

I hi ha un cas especial que convé conèixer: un fitxer de text en una codificació de dos bytes per caràcter, com UTF-16, conté bytes nuls i Git el classificarà com a binari. Es corregeix amb working-tree-encoding:

Git desarà el contingut en UTF-8 dins del repositori (on els diffs funcionen) i l'escriurà en UTF-16LE al teu disc.

Git sap mostrar diferències de text pla. Amb diff=<driver> se li pot donar context sobre el tipus de fitxer, i el resultat millora molt.

Git porta de fàbrica reconeixedors de funció per a molts llenguatges. Només cal declarar-los:

La llista completa és a git help attributes. Hi ha drivers per a Ada, Bash, C/C++, C#, Dts, Elixir, Fortran, Fountain, Kotlin, MATLAB, Objective-C, Perl, Scheme i alguns més.

Aquí hi ha el benefici concret. Recorda de la lliçó 02-05 que cada fragment d'un diff comença amb una línia @@:

Sense driver:

Amb *.js diff=javascript:

Git ha afegit function coincideixAmbFiltre(tasca, filtre) al final de la línia @@. Ara saps quina funció estàs llegint sense obrir el fitxer. Multiplicat pels quaranta fragments d'una revisió, és la diferència entre revisar amb context i revisar a cegues.

Aquest context apareix automàticament a git diff, git show, git log -p i a les plataformes de revisió. I funciona també amb la cerca per funció de la lliçó 02-05:

Sense el driver, -L :nom: no sap trobar la funció.

Si el teu llenguatge no té driver, o l'integrat no reconeix el teu estil, se'n defineix un amb una expressió regular. Són dues peces: la declaració al .gitattributes (versionada) i la definició a la configuració de Git (local, perquè .gitattributes no pot contenir ordres).

L'expressió reconeix function nom(, export function nom(, async function nom( i const nom = ( o const nom = async (, que cobreix l'estil modern de JavaScript.

Recorda la limitació de fons: .gitattributes declara quin driver s'ha de fer servir; la definició del driver viu a git config i no es versiona. Documenta-la al README.md o a l'script d'arrencada del repositori, al costat de core.hooksPath i blame.ignoreRevsFile de les lliçons anteriors.

Hi ha binaris que contenen text: un PDF, un .docx, un full de càlcul, un fitxer d'imatge amb metadades. Per defecte, git diff sobre aquests fitxers diu Binary files differ, que és cert i inútil.

textconv li dóna a Git una ordre que converteix el binari en text, i Git compara aquest text:

Cada ordre rep la ruta del fitxer com a argument i ha d'escriure text a la sortida estàndard.

Ara, si el Bruno canvia el manual d'usuari:

El que cal entendre bé: textconv afecta només la visualització. El contingut emmagatzemat continua sent el PDF binari íntegre, i les fusions continuen sense poder fer-se. És una lent de lectura, no un canvi de format.

Requisit pràctic: l'eina externa (pdftotext, pandoc, exiftool) ha d'estar instal·lada. Si no ho està, git diff falla amb un error. Per això textconv és un bon candidat per al .git/info/attributes local de qui tingui aquestes eines, en lloc del .gitattributes compartit.

Igual que amb els diffs, es pot canviar com es fusiona un tipus de fitxer.

Cada setmana, l'Ana, el Bruno i la Carla afegeixen una línia al CHANGELOG.md, cadascú a la seva branca, sempre al principi:

En fusionar, conflicte garantit, tres cops per setmana. I és un conflicte fals: les tres línies s'han de quedar, no hi ha cap decisió a prendre.

union és un driver integrat (no cal definir res) que, davant d'un conflicte, conserva les línies dels dos costats, sense marcadors. En aquest ordre: primer les de la branca base, després les de l'altre costat.

Amb això, la fusió produeix:

Sense conflicte i sense intervenció.

Quan s'ha de fer servir: fitxers que són llistes acumulatives i on l'ordre no és semàntic.

Advertiment seriós: merge=union mai s'ha d'aplicar a codi. Combina les dues versions d'una funció i produeix una cosa sintàcticament trencada sense avisar de res. El silenci és el seu avantatge i el seu perill: elimina el conflicte, no el resol.

Per a casos com "en un conflicte sobre un fitxer generat, queda't amb el meu i regenera'l":

Git substitueix els marcadors dins de l'ordre: %O és la versió base comuna, %A la teva (i on ha de quedar el resultat), %B la de l'altre costat i %L la mida del marcador de conflicte. El driver ha de retornar 0 si ho ha resolt i diferent de 0 si cal resoldre-ho a mà.

I un advertiment: si el Diego clona el fork i no té aquesta configuració local, Git farà servir el driver per defecte. Els drivers propis es degraden silenciosament, així que no han de ser l'única línia de defensa.

git archive empaqueta el contingut d'un commit en un .tar o .zip, sense el directori .git. És la manera estàndard de produir un paquet distribuïble:

L'atribut export-ignore marca el que no ha d'entrar en aquest paquet. És diferent de .gitignore: aquests fitxers sí que estan versionats; simplement no interessen a qui es descarrega el paquet.

Comprova el resultat abans de publicar:

Un ús molt pràctic: les plataformes d'allotjament generen automàticament el .zip i el .tar.gz de cada etiqueta fent servir git archive, o sigui que export-ignore controla què contenen els paquets de les teves versions sense que hagis de fer res més.

Substitueix marcadors per informació del commit en exportar:

En fer git archive, el fitxer del paquet surt amb els valors emplenats:

És la manera neta que un paquet distribuït sàpiga de quin commit va sortir, i es combina bé amb les etiquetes anotades de la lliçó 05-05. Compte: els marcadors només se substitueixen dins del paquet, no a la teva còpia de treball.

L'atribut filter defineix un parell de conversions: clean en confirmar (del teu disc al repositori) i smudge en extreure (del repositori al teu disc).

El seu ús més important, amb diferència, és Git LFS, que emmagatzema els fitxers grans fora del repositori i hi deixa a dins un punter de text:

Aquestes línies te les escriu git lfs track. El filter=lfs substitueix el fitxer per un punter en confirmar i el recupera en extreure. Git LFS és el contingut de la lliçó 10-03, on s'explica el mecanisme complet, el servidor d'emmagatzematge i les seves implicacions; aquí només interessa saber que és .gitattributes qui l'activa.

Un exemple propi, per entendre el mecanisme (encara que a la pràctica és millor no fer-lo servir):

Compte amb els filtres propis. Si el filtre no és idempotent, o si algú clona sense la configuració, el contingut es desquadra: git status marca fitxers com a modificats sense que ningú els hagi tocat. És una font clàssica de confusió i per això convé reservar-los per a casos on no hi hagi alternativa.

Les plataformes d'allotjament fan servir una biblioteca anomenada Linguist per deduir en quins llenguatges està escrit el teu projecte i què han de mostrar a la vista de diferències. S'ajusta amb aquests atributs:

linguist-generated és el més útil en el dia a dia: fa que els fitxers generats apareguin col·lapsats a les revisions, cosa que elimina de cop el soroll d'un package-lock.json de 8.000 línies en una PR. Enllaça directament amb el que vam dir sobre la mida de la PR a la lliçó 07-02.

Aquests atributs no afecten Git: són convencions que interpreten les plataformes. Si el teu servidor git.exemple.cat no fa servir Linguist, no fan res.

Error 1: crear el .gitattributes i creure que ja està. No arregla el contingut ja confirmat. Cal un git add --renormalize . en un commit a part.

Error 2: renormalitzar barrejat amb altres canvis. Produeix un commit il·legible que, a més, no es pot registrar a .git-blame-ignore-revs, perquè ignorar-lo amagaria també el canvi funcional. Aïlla'l, sempre.

Error 3: renormalitzar sense avisar l'equip. Totes les branques obertes entren en conflicte massiu. Coordina-ho, fes-ho en una PR pròpia i fusiona-la de seguida.

Error 4: confiar només en core.autocrlf. No viatja amb el repositori. N'hi ha prou que el Diego no el tingui configurat perquè el problema torni.

Error 5: aplicar merge=union a codi. Combina les dues versions d'una funció i produeix codi trencat sense avisar. Només per a llistes acumulatives.

Error 6: no marcar els binaris. text=auto encerta gairebé sempre, però quan falla corromp el fitxer. Declarar-los costa una línia.

Error 7: oblidar que les definicions de driver no es versionen. El .gitattributes diu diff=jsmodern; la definició viu a git config i no viatja. Documenta-la al README.md.

Error 8: export-ignore sobre fitxers que la gent sí que necessita. Comprova sempre el resultat amb git archive --format=tar HEAD | tar -t.

Consell 1: * text=auto al primer commit de tot projecte nou. Una línia que evita anys de problemes.

Consell 2: eol=lf explícit als scripts. *.sh text eol=lf evita el bad interpreter: /bin/bash^M que apareix la primera vegada que un script editat a Windows arriba a un contenidor.

Consell 3: git check-attr -a <fitxer> quan alguna cosa no quadri. I git ls-files --eol per veure l'estat real dels finals de línia del repositori.

Consell 4: declara els drivers de diff dels teus llenguatges. És la millora de llegibilitat més barata de les revisions: el nom de la funció a cada @@.

Consell 5: linguist-generated als fitxers de bloqueig. Col·lapsa 8.000 línies de soroll a cada PR.

Consell 6: per a binaris grans, .gitattributes no és la resposta. Marcar-los com a binary evita corrompre'ls, però continuen ocupant el mateix espai a l'historial. Això ho resolen Git LFS (lliçó 10-03) i els consells de la lliçó següent.

1. Crea un repositori amb un estils.css de 10 línies, desat amb LF, i confirma'l sense .gitattributes.
2. Simula el desament des de Windows convertint el fitxer a CRLF:

   sed -i 's/$/\r/' estils.css
   

3. Executa git diff --stat i comprova que les 10 línies apareixen modificades.
4. Comprova l'estat real amb git ls-files --eol.
5. Afegeix un .gitattributes amb *.css text eol=lf, confirma'l i demostra que el diff continua igual de trencat fins que renormalitzes.
6. Renormalitza correctament i verifica amb git ls-files --eol que l'índex queda amb i/lf.

1. Crea un app.js amb tres funcions d'unes cinc línies cadascuna i confirma'l.
2. Modifica una línia dins de la segona funció i executa git diff. Observa la línia @@.
3. Afegeix *.js diff=javascript al .gitattributes i repeteix el git diff. Compara.
4. Prova git log -L :nomDeLaFuncio:app.js i explica què fa.
5. Afegeix un *.pdf diff=pdf amb un textconv (fes servir pdftotext si el tens, o simula'n un amb un script propi que converteixi un format inventat a text) i demostra que git diff en mostra el contingut.

1. Crea un repositori amb un CHANGELOG.md que tingui una capçalera i una entrada.
2. Crea dues branques i afegeix a cadascuna una entrada diferent a la mateixa posició, al principi de la llista.
3. Fusiona la segona dins de la primera i comprova el conflicte.
4. Avorta la fusió, afegeix CHANGELOG.md merge=union al .gitattributes, confirma'l i repeteix la fusió. Verifica'n el resultat.
5. Explica per què aquesta mateixa configuració sobre app.js seria perillosa, amb un exemple concret de codi trencat.
6. Afegeix proves/ export-ignore i .gitattributes export-ignore, i demostra amb git archive --format=tar HEAD | tar -t que no apareixen dins del paquet.

Solució 1:

Deu línies modificades sense haver canviat res visible. Exactament el problema de la Carla.

i/lf: l'índex té LF. w/crlf: el disc té CRLF. attr/ buit: no s'hi està aplicant cap regla.

Continua igual. L'atribut s'aplicarà a partir d'ara, però el contingut del disc continua amb CRLF i Git continua veient-hi diferència.

Índex LF, disc LF, atribut aplicat. El git diff torna a estar net i, a partir d'ara, encara que la Carla desi amb CRLF, Git ho normalitzarà en confirmar.

Solució 2:

La línia @@ està despullada. Aquí la funció es veu per casualitat, perquè el fragment és petit; amb un context de tres línies dins d'una funció de seixanta, no es veuria.

Git hi ha afegit la signatura de la funció. Comprovació que l'atribut s'aplica:

Mostra només l'evolució d'aquella funció al llarg de l'historial, amb el diff de cada canvi que la va tocar. Per localitzar la funció, -L :nom: fa servir el mateix reconeixedor que declara diff=javascript; sense ell, la cerca per nom no funciona de manera fiable.

Git compara la sortida de l'ordre, no els bytes. El contingut emmagatzemat continua sent el fitxer original íntegre.

Solució 3:

Sense conflicte i amb les dues entrades. (Si el merge falla perquè no troba el fitxer d'atributs al commit base, confirma primer el .gitattributes a main i rebasa les branques: els atributs es llegeixen de la còpia de treball en el moment de la fusió.)

5. Per què seria perillós en codi. Suposem que l'Ana i el Bruno modifiquen la mateixa funció:

Amb merge=union, el resultat seria:

Sintàcticament vàlid, silenciosament incorrecte: la segona línia és codi mort i el canvi del Bruno es perd sense que ningú se n'assabenti. En altres casos el resultat ni tan sols compila, i en el pitjor —dues versions d'una condició o d'una clau— produeix codi que fa una cosa diferent de la que volia cap dels dos. I tot això sense cap conflicte que avisi.

Aquesta és la clau: merge=union elimina el conflicte, no el resol. Només és acceptable quan "quedar-se amb totes dues línies" és sempre la resposta correcta, és a dir, en llistes acumulatives on l'ordre no és semàntic.

Ni proves/ ni .gitattributes no hi apareixen: estan versionats, però fora del paquet.

L'essencial d'aquesta lliçó:

• .gitignore decideix què s'ha de versionar; .gitattributes decideix com s'ha de tractar allò versionat. Actua a checkout, commit, diff, merge i archive, i el seu diagnòstic és git check-attr -a.
• El problema dels finals de línia —el de la Carla— es resol amb una convenció: LF al repositori, el natiu al disc. Es declara amb text, text=auto i eol=lf/eol=crlf, i eol controla el disc, no el repositori.
• .gitattributes guanya core.autocrlf i, sobretot, viatja amb el repositori. Aquesta és la raó de fons per la qual és la solució robusta: la política s'aplica a tothom, inclòs el Diego amb el seu fork, sense dependre que ningú configuri res.
• Afegir el fitxer no arregla el passat: cal un git add --renormalize ., en un commit aïllat, coordinat amb l'equip i registrat a .git-blame-ignore-revs (lliçó 08-02). git ls-files --eol mostra l'estat real abans i després.
• binary és la macro de -text -diff -merge i evita que Git corrompi un fitxer binari intentant convertir-ne els bytes. Declarar els binaris explícitament costa una línia i estalvia sorpreses.
• diff=<driver> fa que la línia @@ mostri el nom de la funció, i habilita git log -L :funcio:fitxer. textconv permet veure com a text el contingut d'un binari, només per visualitzar-lo.
• merge=union conserva les línies dels dos costats i elimina els conflictes falsos del CHANGELOG.md. Mai en codi: elimina el conflicte, no el resol.
• export-ignore controla què contenen els paquets de git archive —inclosos els que generen les plataformes per a cada etiqueta—, i export-subst omple la versió i el commit dins del paquet.
• filter=lfs és la porta d'entrada a Git LFS, el mecanisme complet del qual es veu a la lliçó 10-03; i els atributs linguist-*, encara que no afecten Git, col·lapsen el soroll dels fitxers generats a les revisions.

gestor-tasques ja no versiona el que no ha de versionar, i tracta cada fitxer com correspon. Queda pendent l'assumpte més greu dels que vam anunciar en tancar el mòdul 7, i el que no admet improvisació: el fitxer de configuració amb la contrasenya de la base de dades que fa mesos que és a l'historial.

Treure'l d'allà té un procediment amb un ordre de passos que importa moltíssim, i comença per una cosa que no té res a veure amb Git. És la lliçó 08-05: Bones Pràctiques de Seguretat.