A la lliçó anterior vam desmuntar el misteri: una branca és un fitxer de 41 bytes amb un hash a dins, i HEAD és un altre fitxer que diu en quina branca ets. Ara farem servir aquesta maquinària. L'Ana obrirà per fi funcionalitat/comptador-tasques, en Bruno farà el mateix amb funcionalitat/filtre-pendents, i el repositori deixarà de tenir una sola línia de treball.

Crear branques en Git és trivial —ho veuràs en un segon—, però moure's entre elles té matisos que convé dominar des del principi: què passa amb la feina que tens a mitges, per què de vegades Git et deixa canviar de branca i d'altres s'hi nega, i què és aquell estat de HEAD desacoblat que apareix quan menys t'ho esperes i que espanta tothom la primera vegada.

També aclarirem un dubte que arrossega qualsevol que aprengués Git abans del 2019: la diferència entre git checkout i git switch, i per què Git va decidir partir una ordre en dues.

1. git branch: crear sense moure's
2. git switch: moure's
3. git switch -c: crear i moure's en un pas
4. git switch davant de git checkout
5. Crear una branca des d'un punt concret de l'historial
6. git switch -: alternar entre dues branques
7. Canvis sense confirmar en canviar de branca
8. HEAD desacoblat (detached HEAD)
9. El repositori de l'equip, ja amb branques

L'Ana és a main, amb el repositori tal com el vam deixar:

Vol una branca per al comptador de tasques:

Silenci absolut. En Git, el silenci sol voler dir èxit. Vegem què ha passat exactament:

Un fitxer nou, amb el hash del commit on era l'Ana. (Nota lateral interessant: com que el nom de la branca porta una barra, Git ha creat un directori funcionalitat/ dins de refs/heads/. Els noms de branca amb barres són simplement rutes de fitxer; tornarem sobre les convencions de noms a la lliçó 03-06.)

Ara la part important:

HEAD no s'ha mogut. L'Ana continua a main. Ha creat un punter nou, però no s'hi ha situat:

L'asterisc marca la branca actual. Hi ha dues branques i totes dues apunten al mateix commit.

Regla: git branch <nom> crea el punter i no toca res més. Ni HEAD, ni el directori de treball, ni l'àrea de preparació.

Si l'Ana confirmés ara, el commit aniria a main, perquè és on continua apuntant HEAD. És un error clàssic: crear la branca i oblidar-se de canviar-s'hi. Per això, a la pràctica, gairebé mai no es fa servir git branch a seques per començar a treballar; es fa servir la variant de l'apartat 3.

Per situar-se a la branca acabada de crear:

I ara sí:

Això és tot el que ha fet Git en aquest cas: reescriure el fitxer .git/HEAD. Com que les dues branques apuntaven al mateix commit, el directori de treball no ha canviat ni un byte.

Quan les branques apunten a commits diferents, git switch fa alguna cosa més: a banda de reescriure HEAD, actualitza el directori de treball i l'àrea de preparació perquè reflecteixin l'arbre del commit de destinació. És a dir, canvia els fitxers del teu disc. Això és el que passa en les tres operacions internes d'un canvi de branca:

L'Ana escriu el comptador de tasques a app.js i confirma:

Fixa't en el nom entre claudàtors: [funcionalitat/comptador-tasques 6f2b9d4]. Git t'està dient en quina branca ha caigut el commit. És una comprovació gratuïta que convé llegir sempre.

L'Ana afegeix després el marcatge de completades:

Estat actual:

main s'ha quedat quieta a c5d9b1e, exactament com era. La feina de l'Ana està aïllada: pot confirmar tant com vulgui sense tocar la línia principal del projecte.

Crear una branca i no canviar-s'hi és estrany. Per això existeix la drecera:

La -c ve de create. És exactament equivalent a:

Aquesta és la forma que faràs servir el 95 % de les vegades. git branch <nom> a seques queda reservat per als casos en què vols marcar un punt de l'historial sense abandonar el que estàs fent (per exemple, deixar un marcador abans d'una operació arriscada).

Un detall important que sovint es passa per alt: la branca nova es crea des d'on ets ara. Si l'Ana executés aquella ordre estant a funcionalitat/comptador-tasques, la branca nova partiria de 9d1e4b7 i arrossegaria el comptador de tasques, que no és el que vol. Per a la feina d'en Bruno, el punt de partida correcte és main:

O, encara millor, indicant-ho explícitament en una sola ordre —la forma que veurem a l'apartat 5.

Hi ha una variant majúscula, -C, que crea la branca o la reinicia si ja existeix:

Fes-la servir amb cura: si la branca ja existia apuntant a un altre lloc, -C mou el punter sense preguntar i pots deixar commits orfes. -c, en canvi, falla amb fatal: a branch named '…' already exists, que gairebé sempre és el que vols.

Si has vist Git en qualsevol tutorial anterior al 2019, o en la majoria dels que hi ha per internet avui, hauràs vist això:

Funciona. git checkout no està obsolet ni desapareixerà. Però des de Git 2.23 (agost del 2019) existeixen git switch i git restore, i per a feina nova són l'opció recomanada. La raó és senzilla: git checkout feia massa coses diferents.

Mira les tres últimes files, que són les importants. git checkout servia tant per navegar entre branques (una operació innòcua i reversible) com per destruir canvis del directori de treball (una operació irreversible). El mateix verb per a dues coses de risc oposat.

I el desastre potencial era a l'ambigüitat. Imagina que existeix un fitxer anomenat informe i també una branca anomenada informe:

Canvia de branca o descarta els canvis del fitxer? Git resolia a favor de la branca i calia escriure git checkout -- informe (amb el doble guionet separador) per forçar la interpretació de fitxer. Si t'oblidaves del --, podies perdre feina sense avís.

La separació a Git 2.23 elimina l'ambigüitat d'arrel:

• git switch només treballa amb branques. No pot tocar fitxers.
• git restore només treballa amb fitxers. No pot canviar de branca.

Ja vas fer servir git restore a la lliçó 02-04, així que ja coneixes la meitat de la reforma. Aquesta lliçó et dona l'altra meitat.

Què fer a la pràctica:

• Escriu git switch i git restore en la teva feina diària.
• Aprèn a llegir git checkout, perquè el veuràs a tot arreu: documentació antiga, respostes de Stack Overflow, scripts d'integració contínua i companys amb costums arrelats.
• No converteixis els scripts existents que funcionen només per moda; checkout continua sent perfectament vàlid.

Per defecte, una branca nova parteix de HEAD. Però li pots indicar un altre punt de partida com a segon argument, i això val per a les dues formes de l'ordre:

El punt de partida pot ser qualsevol cosa que Git sàpiga resoldre a un commit, amb tota la sintaxi que vas aprendre a la lliçó 02-06:

El primer és el cas d'en Bruno i és la manera correcta de fer-ho: crea la branca a partir de main sense necessitat de canviar-se a main abans. Una ordre en lloc de dues, i sense risc d'oblidar-se'n.

Un cas real on això salva la tarda: has estat programant durant mitja hora a main per despistament, has fet tres commits, i t'adones que haurien d'haver anat en una branca. Solució:

Fixa't que el pas 1 fa servir git branch sense canviar-se: crea el marcador abans de moure res. (git reset --hard és potent i perillós; l'estudiarem a fons a la lliçó 09-02. Aquí és segur perquè els commits continuen assolibles des de la branca nova.)

Quan estàs revisant la feina d'un company i saltes contínuament entre dues branques, escriure el nom sencer cansa. El guionet sol significa «la branca anterior»:

És el mateix concepte que cd - a la shell. Funciona amb noms de branca tan llargs com funcionalitat/exportar-llistat-a-csv i estalvia moltíssimes pulsacions.

Per sota, el guionet és un àlies d'@{-1}, que significa «la branca on era fa un canvi». I n'hi ha més:

Aquesta informació surt del reflog, el registre que Git manté de tots els moviments de HEAD. És la mateixa eina que permet recuperar feina aparentment perduda, i l'estudiarem a la lliçó 09-04.

Aquí hi ha el matís que més confusió genera. Què passa amb el que tens a mitges quan canvies de branca?

La resposta curta: Git intenta emportar-s'ho amb tu, i si no pot fer-ho sense perdre res, s'hi nega.

La resposta llarga depèn de si els canvis afecten fitxers que difereixen entre les dues branques.

L'Ana és a funcionalitat/comptador-tasques i ha començat a retocar README.md, un fitxer que és idèntic a les dues branques:

Ha funcionat, i aquella línia M README.md és Git avisant-te: «aquell fitxer venia modificat i continua modificat». El canvi ha viatjat amb l'Ana a l'altra branca. Continua sense confirmar, al seu directori de treball:

Això és útil a propòsit: et permet començar a escriure alguna cosa, adonar-te que ets a la branca equivocada i corregir-ho sense perdre res.

Ara l'Ana és a main i modifica app.js, que sí que difereix entre main i la branca del comptador (el comptador el va canviar allà):

Git s'hi ha negat, i ha fet bé. Per situar-se a l'altra branca hauria de sobreescriure app.js amb la versió d'allà, i això destruiria els canvis de l'Ana sense possibilitat de recuperar-los, perquè mai no han estat a la base de dades d'objectes.

L'important és que l'operació s'ha avortat del tot. Continues on eres i els teus canvis són intactes.

1. Confirmar. Si la feina té sentit a la branca actual, confirma-la. Si està a mitges, pots fer un commit provisional i arreglar-ho després amb git commit --amend (lliçó 02-04) o amb el rebase interactiu (lliçó 05-02).

2. Descartar. Si el canvi no val res, git restore app.js l'elimina i el canvi de branca passa a estar permès.

3. Desar-ho temporalment. Per al cas real —feina a mitges que vols conservar però que encara no mereix un commit— Git té una eina específica: git stash, que aparta els canvis a un magatzem temporal, deixa el directori net i permet recuperar-los després amb git stash pop:

És una ordre amb bastanta més profunditat de la que suggereix aquest exemple (diverses entrades apilades, incloure fitxers sense seguiment, aplicar en una altra branca…). L'estudiarem sencera a la lliçó 05-04; de moment queda't amb que existeix i amb que és la resposta estàndard a aquest problema.

Existeix l'opció de descartar els canvis i canviar de branca igualment:

(L'equivalent antic era git checkout -f.) És destructiu i irreversible: els canvis no confirmats no són a cap objecte de Git, així que no hi ha cap reflog ni cap recuperació possible. Fes-ho servir només quan estiguis absolutament segur que vols llençar aquella feina.

Recorda la lliçó anterior: HEAD normalment conté ref: refs/heads/<branca>. Però pot contenir directament un hash. Aquest estat s'anomena HEAD desacoblat.

La forma deliberada és demanar-ho:

Git et deixa anar un discurs perquè l'estat és inusual, no perquè sigui perillós. De fet aquell text ja explica gairebé tot el que necessites saber.

Les formes accidentals d'arribar-hi, que són les que espanten:

• git checkout <hash> (sense -b), la més freqüent amb l'ordre antiga.
• git checkout v1.2.0, en situar-se en una etiqueta —les etiquetes apunten a commits, no són branques.
• Durant un git rebase o un git bisect, que treballen internament en aquest estat (mòduls 5 i 6).
• En situar-se a origin/main en lloc de a main, un error molt comú que veurem al mòdul 4.

Un hash directament, sense ref:. HEAD apunta al commit, no a una branca.

El directori de treball conté els fitxers tal com eren en aquell commit. És un estat perfectament legítim: pots compilar, executar les proves, mirar el codi antic o fins i tot confirmar.

No és un accident que calgui evitar; és una eina:

• Revisar com era el projecte en un moment donat. L'Ana vol veure l'aplicació tal com era el dia de la primera confirmació: git switch --detach 1a4c8d6, obre index.html al navegador i llestos.
• Provar si una fallada existia en una versió antiga, situant-se en diferents punts de l'historial.
• Experimentar sense comprometre's. Pots confirmar en aquest estat, i si el resultat no val, tornes a una branca i els commits queden orfes.

El perill no és ser en aquest estat. És confirmar-hi i després marxar sense deixar rastre:

Aquell commit 7d2f9a1 és real i és a la base de dades d'objectes, però cap branca no l'assoleix. Si l'Ana ara fa git switch main:

Git avisa, i fins i tot et dona l'ordre exacta. Però si no llegeixes aquell avís i tanques el terminal, el hash desapareix de la teva vista i el commit queda orfe. Continua sent recuperable durant un temps mitjançant el reflog (mòdul 9), però és una situació que no vols.

Si no has confirmat res (només miraves):

O git switch main, o qualsevol branca. No hi ha res a salvar.

Si has confirmat i ho vols conservar, crea una branca abans de marxar:

Ara HEAD torna a apuntar a una branca, aquella branca apunta a 7d2f9a1, i el commit ja és assolible. Ja no hi ha res orfe.

Si ja has marxat i el commit va quedar enrere, encara pots crear la branca a posteriori, sempre que tinguis el hash (apareix a l'avís, i si el vas perdre, a git reflog):

Recapitulem on som. L'Ana té la seva branca amb dos commits. En Bruno ha estat treballant a la seva, amb els tres commits que ja vam veure al final del mòdul 2 —el filtre de pendents, l'estil de les completades i la correcció del focus—, ara a funcionalitat/filtre-pendents en lloc de directament sobre main.

Per a la resta del mòdul raonarem com si les tres branques fossin en un mateix repositori local, el de l'Ana. Com aconsegueix l'equip que la feina viatgi entre el portàtil de l'Ana i el MacBook d'en Bruno és precisament el tema del mòdul 4; aquí ens concentrem en la mecànica de les branques, que és idèntica vingui la feina d'on vingui.

Tres línies de treball, tres punters, 123 bytes de cost total. Els quatre commits de base són una sola vegada a la base de dades d'objectes i els comparteixen les tres branques.

I aquí hi ha el problema que resoldrem a la lliçó següent: les dues funcionalitats estan acabades i provades, però el projecte real —main— continua exactament on era fa una setmana. Res del que han fet l'Ana i en Bruno no és a la línia principal.

Error 1: git branch <nom> i posar-se a treballar. Crees la branca, se t'oblida el git switch, fas cinc commits i tots cauen a main. Prevenció doble: fes servir git switch -c en lloc de git branch, i llegeix la línia entre claudàtors que imprimeix git commit, que et diu la branca de destinació.

Error 2: crear la branca des del lloc equivocat. git switch -c correccio/urgent estant en una branca de funcionalitat a mitges arrossega tota aquella feina sense acabar dins de la correcció urgent. Abans de crear una branca, comprova on ets amb git branch --show-current, o indica el punt de partida explícitament: git switch -c correccio/urgent main.

Error 3: entrar en pànic amb detached HEAD. No és un error ni una corrupció: és un estat normal. El missatge és llarg perquè explica, no perquè avisi d'un desastre. Si només miraves, git switch - i llestos. Si vas confirmar, git switch -c <nom> abans de marxar.

Error 4: fer servir git checkout -f o --discard-changes per «desencallar». Aquella ordre destrueix els canvis no confirmats de manera irreversible: no són a cap objecte de Git i no hi ha reflog que valgui. Quan Git es negui a canviar de branca, la resposta correcta és confirmar, descartar conscientment amb git restore o desar amb git stash.

Error 5: git switch -C en lloc de -c. La majúscula reinicia una branca existent sense preguntar. Si la branca ja tenia feina, mou el punter i aquella feina queda òrfena. -c falla amb un error clar, que en el 99 % dels casos és el que vols que passi.

Consell 1: una branca per tasca, i de vida curta. Les branques són gratis, així que no hi acumulis feina. Una branca que viu tres setmanes acumula divergència i garanteix conflictes; una que viu dos dies gairebé mai no en té.

Consell 2: activa l'autocompletat de Git. Amb noms com funcionalitat/filtre-pendents, escriure git switch fun<TAB> és la diferència entre treballar còmode i equivocar-se de branca. L'script git-completion.bash ve amb la instal·lació de Git i moltes distribucions l'activen per defecte.

Consell 3: comprova on ets abans de confirmar. El cost és un segon:

Consell 4: no reutilitzis branques velles per a tasques noves. És temptador (ja tinc la branca proves, la reaprofito), però acaba amb historials que no s'entenen i amb fusions que arrosseguen canvis que ningú no ha demanat. Crea una branca nova i esborra la vella quan ja no serveixi; la neteja és el tema de la lliçó 03-06.

En un repositori de proves amb almenys tres commits, crea dues branques —experiment/un i experiment/dos— sense canviar-te a cap d'elles, de manera que:

• experiment/un parteixi del commit actual.
• experiment/dos parteixi de dos commits enrere.

Després, demostra amb ordres que HEAD no s'ha mogut i que les dues branques apunten on correspon.

Dissenya la seqüència mínima d'ordres que provoqui l'error Your local changes to the following files would be overwritten by checkout, i després resol-lo de tres maneres diferents, explicant quan faries servir cadascuna.

Situa't deliberadament en un HEAD desacoblat, fes-hi un commit i conserva'l en una branca nova. Després repeteix el procés però abandonant l'estat sense crear la branca, i observa què et diu Git. Quina dada del missatge és imprescindible anotar?

Solució 1:

Comprovació:

L'asterisc continua a main: HEAD no s'ha mogut. experiment/un coincideix amb main i experiment/dos és dos commits enrere, com demanava l'enunciat.

Verificació byte a byte:

Solució 2:

Per provocar l'error calen dues condicions: un fitxer que difereixi entre les dues branques i una modificació sense confirmar en aquell mateix fitxer.

Les tres resolucions:

Quan: quan el canvi és vàlid i té sentit a la branca actual.

Quan: proves, traces de depuració o qualsevol cosa que no vulguis conservar. És irreversible.

Quan: el cas més habitual del dia a dia, i el motiu que git stash existeixi (lliçó 05-04).

Solució 3:

El commit ja és assolible des d'una branca: no hi ha res orfe.

Segona part, abandonant sense crear branca:

La dada imprescindible és el hash: 3c9d4a2. Mentre el tinguis, recuperar la feina és una sola ordre:

Si a més perds el hash, la situació no és desesperada: git reflog guarda tots els moviments de HEAD durant 90 dies per defecte i permet trobar-lo. És el tema de la lliçó 09-04.

Ja saps crear branques i moure't entre elles amb criteri:

• git branch <nom> crea el punter i no toca res més: ni HEAD, ni el directori de treball, ni l'índex. Útil per marcar un punt sense abandonar el que estàs fent.
• git switch <branca> et situa en una branca: reescriu .git/HEAD i actualitza el directori de treball a l'arbre de destinació.
• git switch -c <nom> [punt-de-partida] és la manera habitual de començar una tasca: crea i es canvia en un pas, i admet qualsevol referència com a origen (una altra branca, un hash, HEAD~2…).
• git switch i git restore substitueixen git checkout des de Git 2.23, separant el que abans era una única ordre ambigua: navegar entre branques i destruir canvis ja no comparteixen verb. checkout continua funcionant i el continuaràs veient en documentació i scripts.
• git switch - alterna amb la branca anterior, igual que cd -.
• En canviar de branca, Git s'emporta els canvis sense confirmar si pot fer-ho sense perdre res, i avorta netament si el fitxer difereix entre les dues branques. Les sortides són confirmar, descartar amb git restore o apartar amb git stash (lliçó 05-04).
• El HEAD desacoblat és HEAD contenint un hash en lloc de ref: refs/heads/…. No és un error: serveix per inspeccionar i experimentar. L'única precaució és crear una branca amb git switch -c abans d'abandonar-lo si hi has confirmat alguna cosa.

L'equip té ara tres branques: main aturada on era, funcionalitat/comptador-tasques amb dos commits de l'Ana i funcionalitat/filtre-pendents amb tres d'en Bruno. Dues funcionalitats acabades que no són al projecte.

Aïllar la feina era la meitat del problema; l'altra meitat és tornar-la a ajuntar. A la lliçó següent, Fusionant Branques, l'Ana integrarà per fi les dues funcionalitats a main. Veurem els dos escenaris que Git distingeix —el fast-forward, en què el punter simplement avança, i la fusió a tres bandes, que crea un commit especial amb dos pares—, com troba Git l'ancestre comú que vam estudiar a la lliçó anterior, i per què de vegades convé forçar un commit de fusió encara que no calgui.