git add e stage: scegliere cosa entra nel commit

git add non significa semplicemente “salva questo file”. Significa: prendi la versione attuale di questa modifica e mettila nell’index, pronta per il prossimo commit.

Questa distinzione cambia il modo in cui lavori. Lo stage non è un casello obbligatorio prima del commit: è il banco di montaggio della storia.

Perché questa lezione conta

Un buon commit non coincide sempre con “tutto quello che ho modificato da stamattina”. Spesso durante lo stesso lavoro fai un fix, un refactor, una correzione di typo e un esperimento. Se committi tutto insieme, il futuro lettore vede una massa indistinta.

Usare bene lo stage ti permette di separare intenzioni diverse anche quando sono nate nello stesso file.

Obiettivo operativo

Alla fine della lezione devi saper scegliere cosa entra nel commit, usare git add -p e verificare lo stage prima di salvare la storia.

Le forme di git add

git add file.txt

Aggiunge allo stage la versione attuale di file.txt.

git add .

Aggiunge modifiche nella directory corrente e sotto-directory. Può comportarsi diversamente se lo lanci da una sottocartella.

git add -A

Aggiunge tutte le modifiche del repository: nuovi file, modifiche, cancellazioni.

git add -u

Aggiunge modifiche e cancellazioni di file già tracciati, ma non nuovi file.

La scelta non è estetica. Se usi sempre git add -A, devi essere ancora più disciplinato nel leggere git diff --staged.

git add -p

Il comando più importante della lezione:

git add -p

Git ti mostra hunk, cioè blocchi di modifica, e ti chiede cosa fare:

y stage this hunk
n do not stage this hunk
s split this hunk
e edit this hunk manually
q quit

s è utile quando Git ha raggruppato modifiche diverse nello stesso hunk. e è potente ma richiede attenzione: modifichi manualmente la patch da staged.

Scenario realistico

Hai modificato checkout.ts:

1. fix reale: impedire doppio submit;
2. refactor: rinominare variabili per chiarezza;
3. debug temporaneo: console.log.

Un commit buono potrebbe essere solo il fix. Il refactor può stare in un commit separato. Il console.log non deve entrare.

Workflow:

git diff
git add -p checkout.ts
git diff --staged
git commit -m "fix(checkout): evita doppio submit"
git diff

Dopo il commit, git diff ti mostra cosa è rimasto fuori. Non è un errore: è lavoro ancora non salvato nella storia.

Stage come review personale

Prima di ogni commit, lo stage dovrebbe rispondere a una domanda:

Questo diff racconta una modifica sola?

Se la risposta è no, hai tre opzioni:

1. separare con git add -p;
2. fare due commit;
3. tornare al codice e separare meglio il lavoro.

Non serve una purezza estrema, ma i commit dovrebbero essere abbastanza piccoli da poter essere revertiti, recensiti e compresi.

File nuovi e cancellazioni

git add -p lavora bene sui file modificati. Per file nuovi, spesso serve aggiungerli interi:

git add src/new-file.ts

Per cancellazioni:

git add deleted-file.ts

oppure:

git add -A

Poi controlla:

git status
git diff --staged --stat
git diff --staged

Laboratorio guidato

Crea un file con tre modifiche:

1. un bugfix;
2. un refactor;
3. un commento temporaneo.

Usa git add -p per staged solo il bugfix. Poi:

1. leggi git diff --staged;
2. fai commit;
3. verifica che refactor e commento siano ancora fuori;
4. crea un secondo commit solo per il refactor;
5. scarta il commento temporaneo.

Output atteso

Due commit puliti:

fix(...): ...
refactor(...): ...

e nessun file temporaneo nello stage.

Errori comuni

Usare git add . senza diff. È il modo più rapido per committare file sbagliati.

Confondere staged e committed. Lo stage è ancora modificabile.

Fare commit misti. Un commit con bugfix, refactor e formattazione insieme sarà difficile da revieware.

Ignorare i file nuovi. I file untracked non entrano nel commit finché non li aggiungi esplicitamente.

Checklist di verifica

• so spiegare la differenza tra git add ., git add -A e git add -u;
• so usare git add -p;
• leggo sempre git diff --staged prima del commit;
• so lasciare fuori lavoro non pronto senza perderlo;
• ogni commit ha una sola intenzione principale.

Collegamenti

• Modulo: Lavorare in solitario: i comandi quotidiani — lezione 6 del corso.
• Si appoggia al modello working tree/index/repository della lezione 2.