git add

Descrizione

Il comando git add aggiunge le modifiche dalla directory di lavoro all'area di staging (chiamata anche index). Con esso, indichi a Git quali modifiche ai file vuoi includere nel prossimo commit. git add non salva nulla nella cronologia da solo — si limita a contrassegnare le modifiche come pronte. Per registrarle effettivamente, esegui git commit successivamente. Per ispezionare cosa è in staging rispetto a cosa non lo è in qualsiasi momento, usa git status.

Questa pagina spiega cosa fa git add, le tre "aree" di Git tra cui si colloca, le opzioni più utili e le modalità interattiva e di modifica delle patch per aggiungere le modifiche pezzo per pezzo.

Le tre aree

Ogni modifica in un progetto Git attraversa tre aree:

• Directory di lavoro — i file che modifichi effettivamente sul disco.
• Area di staging (index) — uno snapshot di ciò che andrà nel prossimo commit.
• Repository — la cronologia dei commit, scritta da git commit.

git add sposta le modifiche dalla directory di lavoro nell'area di staging. git commit poi scrive nel repository tutto ciò che è in staging. Questo flusso in due passaggi è ciò che ti permette di suddividere una directory di lavoro disordinata in commit puliti e mirati.

Perché aggiungere le modifiche all'area di staging?

In molti sistemi di controllo versione, il commit salva uno snapshot di tutto ciò che hai modificato. Git aggiunge deliberatamente l'area di staging nel mezzo, così puoi decidere esattamente cosa contiene ogni commit. Questo è utile quando hai modificato più cose non correlate contemporaneamente: puoi aggiungere all'area di staging e fare il commit di una modifica logica, poi aggiungere e fare il commit della successiva, mantenendo la cronologia leggibile.

Poiché lo staging cattura uno snapshot nel momento in cui lo esegui, git add deve essere eseguito di nuovo ogni volta che apporti ulteriori modifiche che vuoi includere. Se aggiungi un file all'area di staging e poi continui a modificarlo, le modifiche successive rimangono fuori dall'area di staging finché non esegui nuovamente git add.

Opzioni comuni

Aggiunge un singolo file al prossimo commit:

git add <file>

Aggiunge tutte le modifiche all'interno di una directory (ricorsivamente, inclusi i nuovi file):

git add <directory>

Aggiunge tutte le modifiche nell'intero repository — file nuovi, modificati ed eliminati:

git add -A

Aggiunge le modifiche ai soli file già tracciati, incluse le eliminazioni, ma ignora i file non tracciati di nuova creazione:

git add -u

Aggiunge le modifiche in modo interattivo, scegliendo porzioni di file hunk per hunk:

git add -p

git add . vs git add -A vs git add -u

Questi tre comandi si confondono facilmente, quindi vale la pena essere precisi:

Nel Git moderno, sia git add . che git add -A aggiungono le eliminazioni all'area di staging; la differenza riguarda solo l'ambito del percorso. Usa -u quando hai creato file temporanei che non vuoi committare e preferisci non elencarli in .gitignore.

Esempi di git add

Puoi eseguire questi comandi in qualsiasi repository Git. Inizia controllando lo stato corrente con git status, poi aggiungi all'area di staging e fai il commit.

Aggiungere un nuovo file all'area di staging

git add hello.py

Aggiungere più file specifici contemporaneamente

git add hello.py utils.py README.md

Aggiungere tutto all'area di staging, poi fare il commit con un messaggio

git add -A
git commit -m "Add greeting script"

Verificare cosa è in staging prima del commit

git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   hello.py

Per togliere un file dall'area di staging senza perdere le modifiche, usa git restore --staged (oppure, nelle versioni precedenti di Git, git reset):

git restore --staged hello.py

Modalità interattiva

Eseguire git add -p (o scegliere l'opzione patch da git add -i) avvia una sessione di staging interattiva. Git mostra un hunk — un blocco di righe modificate — alla volta e chiede un comando. Le risposte più comuni sono:

• y - aggiungi questo hunk all'area di staging
• n - non aggiungere questo hunk all'area di staging
• q - esci; non aggiungere questo hunk né i rimanenti
• a - aggiungi questo hunk e tutti quelli successivi nel file
• d - non aggiungere questo hunk né quelli successivi nel file
• g - seleziona un hunk a cui andare
• / - cerca un hunk che corrisponda all'espressione regolare fornita
• j - lascia questo hunk in sospeso, vai al prossimo hunk in sospeso
• J - lascia questo hunk in sospeso, vai al prossimo hunk
• k - lascia questo hunk in sospeso, vai al precedente hunk in sospeso
• K - lascia questo hunk in sospeso, vai al precedente hunk
• s - suddividi l'hunk corrente in hunk più piccoli
• e - modifica manualmente l'hunk corrente
• ? - mostra la guida

La suddivisione (s) è particolarmente utile: se Git presenta due modifiche non correlate come un unico hunk, s le separa così puoi aggiungere all'area di staging solo la parte che desideri. Questo è il modo quotidiano per costruire un commit pulito da un file con modifiche miste.

Modifica delle patch

Chiamare git add -e o selezionare e dal selettore interattivo di chunk apre una patch nel tuo editor. Dopo aver chiuso l'editor, l'output viene applicato all'index. Puoi apportare modifiche arbitrarie alla patch, ma alcune modifiche possono produrre output complessi o persino rendere la patch inapplicabile. Se vuoi rifiutare completamente l'operazione, elimina semplicemente tutte le righe della patch. Ecco alcuni elementi comuni che potresti vedere in una patch e quali operazioni di modifica hanno senso per ciascuno.

Le righe che iniziano con + rappresentano contenuto aggiunto. Puoi eliminarle per impedire che le righe aggiunte vengano messe in staging.

Le righe che iniziano con - rappresentano contenuto rimosso. Per impedire che la loro eliminazione venga messa in staging, puoi convertire il - in uno spazio ( ).

Il contenuto modificato è mostrato con righe - (che eliminano il vecchio contenuto) seguite da righe + (che aggiungono il contenuto sostitutivo). Per impedire che la modifica venga messa in staging, converti le righe - in spazi e rimuovi le righe +. Nota che modificare solo metà della coppia può causare cambiamenti confusi all'index.

Errori comuni

• Lo staging è uno snapshot, non un collegamento live. Se esegui git add su un file e poi lo modifichi di nuovo, nell'area di staging c'è solo la versione precedente. Esegui git add un'altra volta per includere le nuove modifiche — git status mostrerà lo stesso file sia in "Changes to be committed" che in "Changes not staged for commit."
• git add non elimina file per te. Aggiunge all'area di staging le eliminazioni di file già tracciati (con -A o -u), ma per eliminare un file dal disco e aggiungerne l'eliminazione all'area di staging in un solo passaggio, usa git rm.
• I file ignorati restano ignorati. I pattern in .gitignore non vengono aggiunti all'area di staging da git add .. Per forzare l'aggiunta di un file ignorato, usa git add -f <file>.
• Niente è ancora definitivo. Lo staging è completamente reversibile. Usa git restore --staged <file> per togliere un file dall'area di staging prima di fare commit.

Esercitazione