Working tree, index, repository: il modello a tre stadi

La maggior parte degli errori quotidiani con Git nasce da una confusione: pensare che esistano solo “file modificati” e “file salvati”. In realtà Git lavora con tre aree distinte.

Il working tree è quello che vedi nel filesystem. L’index è la fotografia preparata per il prossimo commit. Il repository è la storia già salvata.

Quando capisci queste tre aree, comandi come add, restore, reset, commit e diff smettono di sembrare varianti casuali dello stesso verbo.

Perché questa lezione conta

Lo staging non è un passaggio burocratico. È lo strumento che ti permette di costruire commit intenzionali. Puoi avere dieci modifiche su disco e decidere di committarne solo tre. Puoi correggere un file ma lasciare fuori un esperimento. Puoi separare un fix urgente da un refactor iniziato nello stesso momento.

Senza modello a tre stadi, finisci con git add . e commit troppo grandi. Con il modello, Git diventa un editor della storia.

Obiettivo operativo

Alla fine della lezione devi saper dire dove si trova una modifica in ogni momento: solo nel working tree, già nell’index, o già nel repository.

Le tre aree

Working tree. È la copia di lavoro. I file che apri nell’editor, modifichi, cancelli o crei.

Index. È la staging area. Contiene esattamente ciò che entrerà nel prossimo commit. Non è solo una lista di file: è una fotografia intermedia.

Repository. È la directory .git con oggetti, ref e storia. Quando fai commit, l’index diventa un nuovo snapshot nel repository.

Il flusso base:

working tree --git add--> index --git commit--> repository

Il flusso inverso dipende da cosa vuoi annullare:

index --git restore --staged--> working tree non staged
working tree --git restore--> torna alla versione dell'index/HEAD
repository --git reset--> sposta HEAD e, a seconda dell'opzione, index/working tree

Leggere le differenze

Tre diff rispondono a tre domande diverse:

git diff

Mostra cosa hai nel working tree che non è ancora staged.

git diff --staged

Mostra cosa hai nell’index e finirà nel prossimo commit.

git diff HEAD

Mostra tutto ciò che differisce dall’ultimo commit, staged e non staged.

Se prima di committare leggi solo git diff, potresti non vedere cosa hai già staged. Se leggi solo git diff --staged, potresti dimenticare modifiche rimaste fuori.

Esempio operativo

echo "A" > file.txt
git add file.txt
git commit -m "Aggiungi file"

echo "B" >> file.txt
git diff              # vedi B come modifica non staged
git add file.txt
git diff              # ora non mostra nulla
git diff --staged     # B è nello stage

echo "C" >> file.txt
git diff              # C è non staged
git diff --staged     # B è staged

In questo momento lo stesso file contiene due livelli di modifica: una parte già pronta per commit, una parte ancora solo nel working tree.

Perché l’index è potente

L’index ti permette di:

1. separare commit logici;
2. committare solo alcuni hunk;
3. correggere staging accidentale;
4. preparare un commit mentre continui a lavorare;
5. verificare esattamente cosa stai per salvare.

Il comando chiave diventa:

git add -p

Non serve sempre, ma quando un file contiene modifiche miste è la differenza tra storia pulita e commit confuso.

Laboratorio guidato

Crea un repo demo e ripeti questo scenario:

1. crea notes.md e fai il primo commit;
2. aggiungi una riga “fix typo” e una riga “nuova idea”;
3. usa git add -p per staged solo il fix;
4. controlla con git diff e git diff --staged;
5. committa il fix;
6. lascia la nuova idea fuori dal commit.

Annota dopo ogni passo:

working tree:
index:
repository:

Output atteso

Produci una tabella:

comando                    sposta cosa
git add file               working tree -> index
git restore --staged file  index -> fuori dallo stage
git commit                 index -> repository
git diff                   working tree vs index
git diff --staged          index vs HEAD

Errori comuni

Committare senza git diff --staged. Vuol dire non controllare davvero cosa entrerà nel commit.

Usare sempre git add .. È comodo, ma spesso include file temporanei o modifiche non correlate.

Pensare che staged significhi salvato per sempre. Lo stage è preparazione, non storia. La storia nasce col commit.

Checklist di verifica

• so spiegare working tree, index e repository;
• so leggere git diff, git diff --staged e git diff HEAD;
• so creare un commit parziale con git add -p;
• so togliere un file dallo stage senza cancellare il lavoro.

Collegamenti

• Modulo: Fondamenti e modello mentale — lezione 2 del corso.
• Questa lezione prepara i comandi quotidiani del modulo 2.