Ha passat el que era previsible. L'Ana fa mesos que extreu peces reutilitzables de gestor-tasques: el botó amb estat de càrrega, el diàleg de confirmació, el camp de text amb validació. Al principi vivien a app.js; després en un components.js a part. I ara hi ha dos projectes més a l'empresa que els volen fer servir.

L'equip ha fet el que tocava: ha creat un repositori propi, components-ui, a git.exemple.cat/equip/components-ui.git, amb el seu propi historial, les seves pròpies versions etiquetades i els seus propis responsables.

I ara sorgeix la pregunta incòmoda: com fa servir gestor-tasques aquesta biblioteca?

Copiar els fitxers i enganxar-los funciona fins al primer apany, moment en què hi ha tres còpies divergents. I no n'hi ha prou amb "tenir la biblioteca en algun lloc": cal que quedi registrat quina versió exacta de components-ui fa servir cada commit de gestor-tasques, perquè en fer git checkout v1.0.0 d'aquí a sis mesos es pugui reconstruir exactament aquella aplicació.

La resposta nativa de Git a aquest problema són els submòduls. Són potents, són la solució correcta per a certs casos, i tenen fama —merescuda— de mossegar qui no entén com funcionen. Aquesta lliçó va d'entendre'ls bé.

1. Què és exactament un submòdul
2. git submodule add: afegir components-ui
3. Què es confirma exactament: l'objecte de tipus commit
4. Clonar un projecte amb submòduls
5. Actualitzar: el submòdul davant del punter
6. Treballar dins d'un submòdul i el detached HEAD
7. Inspecció: status, foreach i diff --submodule
8. submodule.recurse i altres opcions que treuen dolor
9. Els problemes reals
10. Alternatives: submòduls, subtree, paquets i monorepo

La definició completa, i tota la resta se'n dedueix:

Un submòdul és una entrada a l'arbre del repositori pare que apunta a un commit concret d'un altre repositori, més una línia al fitxer .gitmodules que diu d'on clonar aquell altre repositori.

Dues peces, cap més:

1. El punter: una entrada a l'arbre (lliçó 01-04) el tipus de la qual no és blob ni tree, sinó commit. Desa un hash de 40 caràcters i res més.
2. .gitmodules: un fitxer de text versionat, a l'arrel del pare, que associa cada ruta amb la seva URL.

El que és crucial: el repositori pare no conté el codi de la biblioteca. Conté un post-it que diu "aquí va components-ui, exactament al commit 7f3a9d2". El codi viu a l'altre repositori, amb el seu propi .git, el seu propi historial i les seves pròpies branques.

D'aquí surten les tres propietats que defineixen l'experiència de treballar amb submòduls:

• Reproductibilitat exacta. Cada commit de gestor-tasques fixa una versió concreta de la biblioteca. git checkout v1.0.0 + actualitzar submòduls reconstrueix l'aplicació tal com era.
• Historials independents. Un commit a la biblioteca no apareix a l'historial de l'aplicació. Són dos repositoris diferents amb dos git log diferents.
• Actualització explícita. El punter no es mou sol. Si la biblioteca avança, el pare continua apuntant al mateix commit fins que algú decideix moure'l i el confirma.

Aquesta última propietat és simultàniament la virtut més gran i la font de queixes més gran.

L'Ana ho fa des de l'arrel de gestor-tasques:

Sintaxi:

• Si ometes la ruta, es fa servir el nom del repositori (components-ui/).
• -b <branca> registra una branca de seguiment, útil per a --remote (apartat 5).

El que ha passat, exactament:

Dos fitxers nous, no dos-cents. El directori sencer de la biblioteca apareix com una sola entrada. Aquest és el primer indici visible que no s'està desant el contingut.

El .gitmodules generat:

I el commit:

Fixa't en l'última línia: create mode 160000. Els modes que coneixíem de la lliçó 01-04 eren 100644 (fitxer normal), 100755 (executable) i 040000 (directori). 160000 és el mode especial d'un submòdul, i aquest número és literalment com Git marca "aquí hi ha un punter a un commit extern".

L'Ana ja el pot fer servir des d'index.html:

I envia:

Val la pena veure-ho per dins, perquè entendre-ho aquí evita tota la confusió posterior. Reprenem les eines de la lliçó 01-04:

Aquí és. L'arbre vendor conté una entrada de tipus commit amb mode 160000. No és un tree, no és un blob: és una referència a un objecte commit que ni tan sols és a la base de dades d'objectes de gestor-tasques.

Efectivament: aquell objecte viu al repositori de components-ui, no aquí. El pare només en desa el nom.

I la mida total que ocupa aquesta referència al repositori pare:

Un arbre amb una entrada: unes desenes de bytes. El repositori de gestor-tasques no ha crescut gens per incorporar una biblioteca de 200 commits.

D'aquí es dedueix per què el diff d'un canvi de submòdul té aquell aspecte tan estrany:

Una línia que canvia. Tot el contingut de la biblioteca pot haver canviat, però per al pare això és un punter que es mou.

En Bruno clona el projecte per primera vegada:

El directori existeix però és buit. Aquest és el primer entrebanc clàssic, i li passa a tothom: git clone no baixa els submòduls per defecte.

Hi ha dues maneres d'arreglar-ho.

Clona el pare i, tot seguit, inicialitza i clona cada submòdul al commit fixat.

O en una sola ordre:

La separació en dos passos té sentit quan l'entens:

El pas d'init existeix perquè permet canviar la URL localment abans de clonar (per exemple, per fer servir un mirall intern o HTTPS en lloc d'SSH) sense tocar el .gitmodules que comparteix tot l'equip:

També se'n pot inicialitzar només algun, en projectes amb molts:

Aquí hi ha la distinció que més confusió genera, i mereix un encapçalament propi.

Hi ha dues actualitzacions diferents i fan coses oposades:

És el cas normal, i el que s'executa després d'un git pull:

L'Ana ha pujat un commit que mou el punter de la biblioteca. En Bruno fa git pull del pare, i submodule update deixa la seva còpia de components-ui exactament al commit que l'Ana va fixar. Sincronització, no actualització.

Git ha fet fetch al submòdul i ha fet checkout de la punta de la seva branca de seguiment. Quina branca? Per aquest ordre:

1. La indicada a .gitmodules amb branch = <branca> (o git submodule add -b).
2. Si no n'hi ha cap, HEAD del remot, que sol ser main.

I ara el que és important: això encara no ha canviat res a l'historial del pare. És un canvi sense confirmar:

(new commits) significa: "el submòdul és en un commit diferent del que jo tinc registrat". Perquè l'actualització sigui real i arribi a la resta de l'equip, cal confirmar-la al pare:

La regla que resumeix tot l'apartat: actualitzar el submòdul és un canvi al teu disc; actualitzar el punter és un commit al pare. Si no ho confirmes, ningú més no veu l'actualització, i el següent git submodule update te la desfà.

La Carla necessita arreglar el diàleg de confirmació, que és a la biblioteca. Entra al directori del submòdul:

Detached HEAD, l'estat de la lliçó 03-02. I té tota la lògica del món: el pare no diu "fes servir la branca main de la biblioteca", diu "fes servir el commit 7f3a9d2". Git fa exactament això, i un checkout d'un commit solt deixa HEAD desacoblat.

Conseqüència perillosa: si la Carla edita i confirma aquí sense més, crea un commit que no pertany a cap branca. Tan bon punt algú faci git submodule update, aquell commit queda orfe i només es recupera pel reflog (lliçó 09-04).

El procediment correcte té quatre passos:

El pas 3 és el que s'oblida, i ometre'l és la fallada més greu de tots els submòduls. Si la Carla confirma el punter al pare sense haver publicat el commit del submòdul, el resultat és:

El pare apunta a un commit que no existeix enlloc llevat del disc de la Carla. El projecte està trencat per a tot l'equip fins que ella el publiqui.

Git té una xarxa de seguretat per a això, i cal activar-la:

check és l'opció recomanada: t'avisa i t'obliga a decidir, en lloc de publicar coses pel seu compte.

El primer caràcter és un indicador d'estat, i cal saber llegir-lo:

Exemples de les situacions problemàtiques:

→ En Bruno acaba de clonar sense --recurse-submodules.

→ Algú ha mogut el submòdul i no ho ha confirmat al pare.

Amb --recursive baixa pels submòduls imbricats.

Executa una ordre a cada submòdul:

Dins de l'ordre, Git defineix variables útils:

Per defecte, un canvi de submòdul es veu com aquella línia de Subproject commit. --submodule=log mostra els commits que hi ha de diferència, que és infinitament més informatiu:

Tres commits de diferència, amb els seus assumptes. Els modes disponibles:

I com que és el que es vol gairebé sempre, convé fixar-ho:

Amb status.submoduleSummary, git status també resumeix els commits pendents en lloc de dir només (new commits).

La major part del patiment amb submòduls ve d'oblidar el --recurse-submodules en alguna ordre. Aquesta opció l'activa per defecte per a gairebé totes:

A partir d'aquí, git pull, git switch, git checkout, git reset i altres actualitzen els submòduls automàticament. És la primera configuració que hauria de posar qualsevol que treballi amb submòduls.

Nota: submodule.recurse no afecta git clone, que continua necessitant el seu --recurse-submodules explícit.

El joc complet de configuració recomanada:

I un grapat d'ordres que resolen situacions concretes:

Aquest últim mereix explicació: deinit el desregistra, git rm treu l'entrada de l'arbre i la línia de .gitmodules, i el rm -rf de .git/modules/ esborra el repositori intern que Git conserva (des de la versió 1.7.8, el .git del submòdul no és dins del seu directori, sinó a .git/modules/<nom> del pare, i al directori del submòdul hi queda un fitxer .git que hi apunta — la mateixa tècnica que veurem amb worktree a la lliçó 06-06).

Tot l'anterior funciona. Aquests són els entrebancs que es donen a la pràctica i la seva solució.

Símptoma. Algú clona i vendor/components-ui/ no té res. L'aplicació no arrenca.

Causa. git clone sense --recurse-submodules.

Solució. git submodule update --init --recursive. I prevenció: documentar-ho al README.md, i —millor encara— un hook post-checkout de la lliçó 06-01 que avisi:

Ja vist a l'apartat 6: algú va confirmar el punter sense publicar el commit del submòdul.

Solució. Que aquella persona faci git push al submòdul. Prevenció: push.recurseSubmodules check.

Símptoma. git status al pare diu modified: vendor/components-ui (modified content) i no hi ha manera que desaparegui.

Causa. Algú ha editat fitxers dins del submòdul sense confirmar-los allà.

Solució, segons el que vulguis:

L'opció ignore accepta none (per defecte), untracked (ignora fitxers sense seguiment), dirty (ignora també les modificacions) i all (ignora fins i tot un punter diferent). all és perillós: amaga exactament la informació que necessites veure.

Símptoma. La Carla passa d'una branca que té el submòdul a una altra que no el té (o que el té en una altra versió), i apareixen fitxers estranys o el directori es queda amb contingut antic.

Causa. El checkout del pare mou el punter, però el contingut del directori del submòdul no s'actualitza sol llevat que ho demanis.

Solució. submodule.recurse true, o recordar-se de git checkout --recurse-submodules <branca>.

I un cas especialment molest: en tornar a una branca anterior a la incorporació del submòdul, el directori es queda allà amb contingut i sense seguiment. No és una fallada: és que Git no esborra directoris que contenen un repositori per no destruir feina.

Dues branques actualitzen el submòdul a commits diferents:

No hi ha marcadors de conflicte per editar: el conflicte és quin hash ha de guanyar. La resolució consisteix a decidir el commit correcte:

Sovint la resposta correcta no és cap dels dos, sinó un commit posterior del submòdul que conté els canvis de totes dues branques. Fusiona'ls primer dins del submòdul, i després apunta-hi.

I el problema del qual menys es parla: els submòduls afegeixen un pas a tot. Cada pull pot necessitar un submodule update; cada canvi a la biblioteca són dos commits i dos push; cada persona nova s'equivoca en clonar la primera vegada. Res d'això no és greu per separat, però s'acumula.

Per això la pregunta important no és "com es fan servir els submòduls?", sinó "és aquesta l'eina adequada per al meu cas?". Anem-hi.

Hi ha quatre maneres raonables de compondre un projecte a partir de diverses peces.

Un paràgraf per a cadascuna:

git subtree fa el contrari que els submòduls: copia el contingut de la biblioteca dins del pare i el manté sincronitzat amb fusions. Qui clona no ha de fer res d'especial, perquè el codi hi és. A canvi, el repositori creix, l'historial es barreja i contribuir de tornada a la biblioteca és incòmode. És una bona opció quan consumeixes una dependència i rarament la modifiques, i quan la fricció del --recurse-submodules és inacceptable (per exemple, si el projecte el clona gent aliena a l'equip). Les ordres bàsiques són git subtree add, pull i push; no ho desenvolupem aquí perquè mereixeria la seva pròpia lliçó.

Un gestor de paquets (npm, pip, Maven, Cargo...) és, a la majoria dels projectes moderns, la resposta correcta. Si components-ui es pot publicar com a paquet —encara que sigui en un registre privat de l'empresa—, l'equip declara "@equip/components-ui": "^2.1.0" al seu package.json, el fitxer de blocatge garanteix la reproductibilitat, i tota la maquinària de versions semàntiques (lliçó 05-05) treballa a favor seu. Que Git pugui fer això no vol dir que ho hagi de fer. Abans de triar submòduls, pregunta't sempre si un paquet resoldria el problema.

El monorepo —un únic repositori amb l'aplicació i la biblioteca a dins— elimina el problema d'arrel: un commit pot canviar totes dues alhora, i sempre són coherents. És el que fan moltes empreses grans. El preu és un repositori que creix molt i necessita eines pròpies per a permisos, compilacions parcials i rendiment. Aquell escenari, amb les seves tècniques —clons parcials, sparse-checkout, clons superficials—, és el tema de la lliçó 10-04: Escalant Git per a Projectes Grans.

Els submòduls guanyen quan es compleixen alhora diverses d'aquestes condicions:

• La dependència és codi font que compiles al costat del teu, no un artefacte publicable.
• Necessites fixar un commit exacte, no un rang de versions.
• Modifiques la biblioteca amb una certa freqüència i vols que sigui un repositori de primera classe.
• No hi ha (o no vols muntar) un registre de paquets intern.
• L'equip és petit i es pot formar en la mecànica.

Casos reals típics: temes i connectors d'un CMS, biblioteques C/C++ compilades des del codi font, configuracions compartides entre projectes, microprogramari amb components de tercers.

I una menció que cal fer aquí perquè de vegades es confon: si el teu problema no és codi compartit sinó fitxers grans i binaris —imatges d'alta resolució, vídeos, models, executables— la resposta no és cap de les quatre, sinó Git LFS, que substitueix aquests fitxers per punters de text i desa el contingut en un magatzem a part. És el tema de la lliçó 10-03: Git LFS per a Fitxers Grans.

Per a gestor-tasques, l'equip acaba prenent aquesta decisió: submòdul de moment, perquè components-ui és en ple desenvolupament, es modifica cada setmana i no compensa publicar un paquet a cada canvi. Quan la biblioteca s'estabilitzi i altres equips comencin a consumir-la, passaran a publicar-la al registre npm intern. És una decisió assenyada: la manera de compondre un projecte pot canviar amb la seva maduresa.

Error 1: clonar sense --recurse-submodules. L'error número u. Directori buit i aplicació trencada. Solució: git submodule update --init --recursive.

Error 2: confirmar el punter sense publicar el commit del submòdul. Trenca el projecte per a tots els altres. Prevenció: git config push.recurseSubmodules check.

Error 3: treballar al submòdul sense sortir del detached HEAD. Els commits queden orfes. Fes git switch <branca> abans de tocar res.

Error 4: confondre submodule update amb submodule update --remote. El primer obeeix el pare; el segon porta el que és nou del remot. Són oposats.

Error 5: oblidar confirmar al pare després d'actualitzar. Si no hi ha commit al pare, l'actualització només existeix al teu disc.

Error 6: fer servir submodule.<n>.ignore = all. Amaga precisament la informació que necessites veure. Com a molt, dirty.

Error 7: intentar esborrar un submòdul amb rm -rf. Deixa restes a .git/config, .gitmodules i .git/modules/. Fes servir la seqüència deinit + git rm.

Error 8: triar submòduls per defecte. Gairebé sempre hi ha una alternativa més simple. Justifica la tria.

Consell 1: git config --global submodule.recurse true, sempre. És la configuració que més dolor evita.

Consell 2: diff.submodule log i status.submoduleSummary true. Converteixen hashos il·legibles en llistes de commits.

Consell 3: apunta a commits estables, preferiblement etiquetats. Un submòdul apuntant a la punta de main d'un altre equip és una font inesgotable de sorpreses. git describe --tags dins del submòdul et diu on ets.

Consell 4: documenta la mecànica al README.md. Cinc línies amb el clone --recurse-submodules i el submodule update --init estalvien una hora a cada persona nova.

Consell 5: un hook post-checkout que avisi de submòduls sense inicialitzar. És l'ús perfecte del que hem après a la lliçó 06-01.

Consell 6: en actualitzar el punter, explica per què al missatge. "Actualitza components-ui" no diu res; "Actualitza components-ui a v2.2.0 per la correcció del focus" converteix aquell commit en informació útil.

Treballant en local (sense servidor remot):

1. Crea un repositori biblioteca amb tres commits i una etiqueta v1.0.
2. Crea un repositori aplicacio amb dos commits.
3. Afegeix biblioteca com a submòdul d'aplicacio a vendor/biblioteca i confirma-ho.
4. Inspecciona l'arbre amb git cat-file -p HEAD^{tree} i localitza l'entrada de mode 160000.
5. Comprova que l'objecte commit al qual apunta no existeix a la base d'objectes del pare.

Sobre l'exercici anterior:

1. Afegeix dos commits nous a biblioteca.
2. A aplicacio, comprova que git status no diu res (el punter continua igual).
3. Executa git submodule update --remote i observa què canvia a git status.
4. Confirma el punter nou amb un missatge que expliqui el perquè.
5. Comprova el diff del punter amb --submodule=short, --submodule=log i --submodule=diff.

1. Clona aplicacio sense --recurse-submodules i comprova el directori buit i la sortida de git submodule status.
2. Arregla-ho amb git submodule update --init.
3. Al clon, entra al submòdul i comprova que ets en detached HEAD. Fes un commit allà sense canviar de branca i observa l'avís de Git.
4. Recupera aquell commit orfe posant-lo en una branca.
5. Elimina el submòdul del pare del tot (deinit, git rm, .git/modules/) i verifica que no queden restes.

Solució 1:

L'opció -c protocol.file.allow=always cal des de Git 2.38 per fer servir submòduls amb rutes locals; amb URLs https:// o git@ no és necessària.

Aquí hi ha el mode 160000 i el tipus commit.

Confirmat: l'objecte no és a la base de dades del pare. Només se'n desa el nom.

Solució 2:

El pare continua apuntant al commit fixat: els commits nous de la biblioteca li són indiferents. Aquesta és la propietat, no una fallada.

Molt més útil: dos commits, amb els seus assumptes.

Mostra el contingut real dels canvis dins del submòdul.

Prefix espai: tot en ordre.

Solució 3:

El - inicial és el diagnòstic: no inicialitzat.

El + avisa: el submòdul és en un commit diferent del registrat. I aquell commit no és a cap branca:

Ja és fora de perill. Sense aquest pas, un git submodule update l'hauria deixat orfe.

Els tres llocs on viu un submòdul, nets. Un rm -rf a seques hauria deixat restes als tres.

Els submòduls són la resposta nativa de Git a compondre un projecte amb diversos repositoris, i tot el seu comportament es dedueix d'una sola idea. L'essencial:

• Un submòdul és un punter a un commit concret d'un altre repositori, desat com una entrada d'arbre de mode 160000 i tipus commit, més una línia a .gitmodules. El pare no conté el codi de la biblioteca.
• Això dona reproductibilitat exacta (cada commit del pare fixa una versió de la dependència), historials independents i actualització explícita: el punter no es mou sol.
• git submodule add <url> <ruta> l'incorpora; el commit resultant toca dos fitxers, no dos-cents.
• Clonar requereix --recurse-submodules, o git submodule update --init --recursive després. És l'error més freqüent.
• Hi ha dues actualitzacions oposades: submodule update posa el submòdul on diu el pare; submodule update --remote porta el que és nou del remot i cal confirmar el punter al pare perquè existeixi de debò.
• Dins del submòdul s'és en detached HEAD: canvia a una branca abans de treballar, i publica el commit del submòdul abans de confirmar el punter (push.recurseSubmodules check).
• git submodule status amb els seus prefixos ( , -, +, U), foreach i diff --submodule=log són les eines d'inspecció. submodule.recurse true, diff.submodule log i status.submoduleSummary true eliminen la major part de la fricció.
• Els problemes reals són sempre els mateixos: directoris buits, punters a commits sense publicar, canvis sense confirmar dins del submòdul, canvis de branca al pare i conflictes de punter. Tots tenen solució coneguda i tots tenen prevenció.
• I sobretot: no són l'opció per defecte. Compara'ls amb git subtree, amb un gestor de paquets (sovint la millor resposta) i amb el monorepo (lliçó 10-04), i tria amb criteri. Per a binaris grans, l'eina és Git LFS (lliçó 10-03).

gestor-tasques ja es compon de dos repositoris, i l'equip té la traçabilitat que necessitava. Però queda un problema pendent des del final del mòdul 5, i és el de la Carla.

La Carla treballa a funcionalitat/esborrat-multiple, una branca llarga i a mitges. Cada vegada que arriba un avís urgent —una fallada en producció, una revisió de codi per atendre, un dubte sobre una altra branca— ha de fer git stash, canviar de branca, resoldre, tornar i git stash pop. Deu vegades al dia. I amb el submòdul acabat d'afegir la cosa empitjora, perquè cada canvi de branca arrossega també la seva actualització.

La seva primera idea és clonar el repositori dues vegades. Funcionaria, però duplica l'espai, duplica els fetch i deixa dos repositoris amb historials que cal mantenir sincronitzats a mà. Hi ha una solució molt millor, integrada a Git i sorprenentment poc coneguda: diversos directoris de treball compartint una única base de dades d'objectes. És la lliçó 06-06: Múltiples Còpies de Treball amb git worktree.